Getting Started

Minimal Setup

Installation

composer require apnet/bootstrap

Add the service provider to config/app.php:

'providers' => [
    // ...
    Apnet\Bootstrap\BootstrapServiceProvider::class,
],

Basic Usage The package provides a Bootstrap facade for quick access to common Laravel bootstrapping utilities. First, publish the config:

php artisan vendor:publish --provider="Apnet\Bootstrap\BootstrapServiceProvider" --tag="config"

Configure default paths in config/bootstrap.php:

'paths' => [
    'views' => resource_path('views'),
    'routes' => base_path('routes'),
    'config' => config_path(),
],

First Use Case: Auto-Loading Routes Use the Bootstrap facade to dynamically load routes from a directory:

use Apnet\Bootstrap\Facades\Bootstrap;

Bootstrap::loadRoutesFrom('api'); // Loads routes from `routes/api.php`

Implementation Patterns

Common Workflows

1. Dynamic View Loading

Load views from a custom directory (e.g., for modular apps):

Bootstrap::setViewPath(app_path('Modules/MyModule/Resources/views'));
Bootstrap::loadViews();

2. Service Provider Bootstrapping

Use the package to defer heavy initialization until runtime:

public function boot()
{
    Bootstrap::lazyLoad(function () {
        // Expensive operations (e.g., caching, DB connections)
        Cache::remember('expensive_data', 3600, function () {
            return DB::table('large_table')->get();
        });
    });
}

3. Environment-Specific Configs

Override configs based on the environment:

if (app()->environment('local')) {
    Bootstrap::overrideConfig('app.debug', true);
}

4. Middleware Integration

Dynamically register middleware for specific routes:

Bootstrap::registerMiddlewareForRoute('api', \App\Http\Middleware\ApiAuth::class);

5. Event Listeners

Attach listeners to boot events:

Bootstrap::onBoot(function () {
    event(new App\Events\ApplicationReady);
});

Integration Tips

Modular Applications Use Bootstrap::module() to scope paths/configs to a module:

Bootstrap::module('admin', [
    'views' => 'Modules/Admin/Resources/views',
    'routes' => 'Modules/Admin/Routes',
]);

Testing Reset the bootstrap state in tests:

public function tearDown(): void
{
    Bootstrap::reset();
    parent::tearDown();
}

Custom Directories Extend the package by adding new path types (e.g., Bootstrap::loadTranslationsFrom()) via service provider bindings.

Gotchas and Tips

Pitfalls

State Persistence The package maintains internal state (e.g., loaded paths, overrides). Forgetting to call Bootstrap::reset() in tests can lead to flaky test results.
Path Resolution Paths are resolved relative to Laravel’s root. Hardcoding absolute paths (e.g., /var/www/views) will break when the app is moved.
Overriding Configs Config overrides are applied after Laravel’s default config is loaded. Overriding app.timezone too late may not affect Carbon’s timezone.
Middleware Registration Middleware registered via Bootstrap::registerMiddlewareForRoute() must match the route’s URI exactly (no wildcards). Use Route::group() for flexible middleware.
Lazy Loading Bootstrap::lazyLoad() callbacks run once, during the first request. Subsequent calls to Bootstrap::lazyLoad() will be ignored.

Debugging Tips

Check Loaded Paths Dump the current paths with:
```
dd(Bootstrap::getPaths());
```
Verify Config Overrides Use:
```
dd(Bootstrap::getOverrides());
```
Enable Debug Mode Set 'debug' => true in config/bootstrap.php to log bootstrap events to storage/logs/bootstrap.log.

Extension Points

Custom Path Types Extend the Apnet\Bootstrap\Contracts\PathResolver interface to support new path types (e.g., Bootstrap::loadAssetsFrom()).
Hooks Bind to the bootstrap.loaded event for post-bootstrap logic:
```
event(new BootstrapLoaded);
```
Service Provider Extensions Override the default service provider by publishing and modifying the provider class:
```
php artisan vendor:publish --provider="Apnet\Bootstrap\BootstrapServiceProvider" --tag="provider"
```

Macros Add custom methods to the Bootstrap facade:

\Apnet\Bootstrap\Facades\Bootstrap::macro('loadAssets', function ($path) {
    // Custom logic
});

Config Quirks

Default Values The package uses null as a default for unset config values. Explicitly set null in config/bootstrap.php to avoid unexpected behavior.
Caching Disable Bootstrap::cacheConfig() in development to ensure real-time config updates.
Environment Variables Paths can reference environment variables (e.g., 'views' => env('CUSTOM_VIEWS_PATH')), but validate these exist in bootstrap/app.php.

Bootstrap Laravel Package