# Project Setup

This guide describes how to set up a Laravel project with the Globals package as the basis for a new project.

## Preliminary note

The Globals package should only be installed in new Laravel applications. Attempting to install the Globals package in an existing Laravel application will result in unexpected behavior and problems.

## Installing the base

The basic requirement for all projects is Laravel with Jetstream and Livewire. To set up these components, the following commands must be executed in sequence:
```bash

composer create-project laravel/laravel:^12 #example-app#

cd #example-app#

composer require laravel/jetstream

php artisan jetstream:install livewire --dark

npm install

```
The character string `#example-app#` must be replaced by the desired directory name.

## Install Globals package

The globals package provides models, repositories, service classes, middlewares, traits and much more to supplement the base.

### Regular installation

As the package is not in a public repository, the repository must be registered in the first installation step. To avoid having to register a separate repository for each private package, selected packages are made available via a central repository:
```bash
composer config repositories.bplan/composer-packages composer https://satis.bplan.solutions
```

It may happen that an error message is displayed that criticizes the structure of the command. In this case, the `composer.json` can also be extended manually as follows:

```json

    "repositories": {
        "bplan/composer-packages": {
            "type": "composer",
            "url": "https://satis.bplan.solutions"
        }
    }
    
```

The package can then be installed as usual:
```bash
composer require bplan-base/globals
```

### Installation for development

To install the Globals package as a development package, for example because it is to be developed in parallel with the development of the project, a repository entry must be created for the local working copy of the package:
```bash
composer config repositories.bplan-base/globals path #/local/path/to/bplan-base/globals#
```
The actual local path must be used instead of `#/local/path/to/bplan-base/globals#`. The path specification can be absolute or relative to the project directory.

The result in `composer.json` then looks like this:
```json

    "repositories": {
        "bplan/composer-packages": {
            "type": "path",
            "url": "/local/path/to/bplan-base/globals/"
        }
    }
    
```

The command for the installation must be adapted as follows:
```bash
composer require bplan-base/globals:@dev
```
This creates a symbolic link in the project under `vendor/bplan-base` that refers to the working copy of the Globals package.

### Globals setup

After installation, you can start setting up the Globals package:
```bash
php artisan globals:setup
```
Executing the command performs the following tasks in the project directory:

* Replacing some default files.
* Adding new files.
* Extending the `.env` file and creating the template configuration file for production.
* Creating the storage link.
* Installing an API package (optional).
* Installing the CodeGenerator (optional).
* Installing and setting up the “wikimedia/composer-merge-plugin” package.

Once the setup is complete, you must reinstall NPM:
```bash
npm install
```

Once the setup is complete, the migrations and seeds can be executed. As some migrations have been replaced, a `migrate:fresh` must be performed:
```bash
php artisan migrate:fresh --seed
```
If the CodeGenerator has been installed and is active, subsequent migrations must always be started with `migrate:fresh`.

## Code Generator

The Code Generator uses specially prepared migrations to automatically generate classes based on the table schema defined in it and an extended configuration.

To activate the code generator, the following setting must be made in the `.env` file:
```toml
CODE_GENERATOR_ACTIVE = true
```

During development, the Code Generator may not be able to complete its work due to an error that occurs during the execution of the migration. It may then not be possible to run the migration again because the required relations have not been created.
In this case, the following configuration setting can be entered in the `.env` file:
```toml
CODE_GENERATOR_SKIP_ROUTING = true
```
Both settings are automatically added to the `.env` file by the setup.

The use of the code generator is described in the associated `README` file.

## Dev packages

When setting up the globals package, the file `composer.local.json.in` is created in the root directory of the project. This is the template file that must be renamed or copied to `composer.local.conf` for use. It is then loaded automatically when `composer install` or `composer update` is executed.

**Important:**
The file `composer.local.conf` must not be versioned.

Packages that are not or should not be part of the project can be registered in this file. This is useful, for example, if a package is only required for development or if a package is to be developed that needs to be loaded from the local hard disk.
Example:
```json
{
    "require": {
        "vendor/package": "@dev"
    },
    "require-dev": {
        "bplan-base/laravel-code-generator": "@dev"
    },
    "repositories": [
        {
            "name": "vendor/package",
            "type": "path",
            "url": "/local/path/to/vendor/package",
            "options": {
                "symlink": true
            }
        },
        {
            "name": "bplan-base/laravel-code-generator",
            "type": "path",
            "url": "/local/path/to/bplan-base/laravel-code-generator",
            "options": {
                "symlink": true
            }
        }
    ]
}

```

