Framework Laravel Package

Getting Started

Treat this as a Laravel distribution/customization layer, not a plug-and-play library. The README tells you almost nothing about behavior, so the first task is reconnaissance, not integration.

Minimal setup:

# 1. Verify the hard requirements first
php -v                       # must be >= 8.4.21 (README recommends it to dodge 8.4.x bugs)
composer --version           # v2+

# 2. Pin deliberately — 0.x releases can break
composer require sikessem/framework:^0.11

# 3. Find out what actually got installed
composer show sikessem/framework
cat vendor/sikessem/framework/composer.json

Where to look first, in order:

1. vendor/sikessem/framework/composer.json — check the illuminate/* constraints, extra.laravel.providers, and extra.laravel.aliases. This is the real compatibility contract, not the README.
2. vendor/sikessem/framework/src/ — look for *ServiceProvider, config/, routes/, Console/, Http/Middleware, Database/Migrations. These are your integration surface.
3. The sikessem/starter kit — the README explicitly names it as the intended host. Read its composer.json, config/, and bootstrap/app.php (or config/app.php on older skeletons) to see how the framework is meant to be wired.
4. php artisan about and php artisan list after install — diff against a vanilla app to spot new commands, drivers, and config keys.

First use case: scaffold sikessem/starter in a throwaway directory, run it, then diff it against a fresh laravel/laravel install. That diff is effectively your undocumented "what this package does" document. Only after that decide whether to (a) build on the starter, or (b) bolt individual pieces onto an existing app.

If a starter reference isn't viable, do a spike branch: fresh Laravel skeleton + sikessem/framework, boot it, run php artisan route:list, hit the welcome route, and confirm nothing in the service container is shadowed.

Implementation Patterns

Pattern 1 — Full-stack adoption via the starter (intended path).

Build on sikessem/starter rather than retrofitting. This is what the package is optimized for. Keep your app-specific code in app/ and avoid editing files under vendor/.

Pattern 2 — Partial adoption in an existing app.

Register only the providers/modules you need. Laravel auto-discovery handles this if extra.laravel.providers is present; otherwise register explicitly:

// bootstrap/providers.php (Laravel 11+) or config/app.php
return [
    App\Providers\AppServiceProvider::class,
    Sikessem\Framework\...\ServiceProvider::class, // verify namespace from vendor/src
];

Then isolate every dependency behind a config flag so you can fall back to vanilla:

// config/app.php or a dedicated config/services.php key
'sikessem' => [
    'enabled' => env('SIKESSEM_ENABLED', false),
],

// AppServiceProvider::register()
if (config('app.sikessem.enabled')) {
    $this->app->register(\Sikessem\Framework\...\ServiceProvider::class);
}

This lets you A/B test the framework against vanilla behavior and gives you a rollback switch.

Pattern 3 — Config publishing and env namespacing.

php artisan vendor:publish --tag=sikessem-config
# or, if no tag exists:
php artisan vendor:publish --provider="Sikessem\Framework\...\ServiceProvider"

If published files collide with your own config/ keys, namespace them (config/sikessem.php) rather than overwriting config/app.php. Re-run with --force only intentionally.

Pattern 4 — Upgrade workflow.

git switch -c chore/sikessem-0.12
composer update sikessem/framework --with-dependencies
php artisan config:clear && php artisan route:clear && php artisan view:clear
php artisan about
composer test   # or your suite

Always run the upgrade against your own test suite, not just the framework's (which may not exist).

Pattern 5 — Integration tests as documentation.

Since behavior is undocumented, encode assumptions in tests:

it('boots with sikessem providers', function () {
    expect(app()->getLoadedProviders())->toHaveKey('Sikessem\...\ServiceProvider');
});

it('keeps default routing when sikessem is disabled', function () {
    config(['app.sikessem.enabled' => false]);
    // assert vanilla behavior
});

Pattern 6 — Deployment/CI.

Pin in composer.lock, install with composer install --no-dev --optimize-autoloader, and add PHP 8.4.21+ to your CI matrix. Run composer audit in CI (small-community package = you are the security net).

Gotchas and Tips

Compatibility is the biggest unknown. The README doesn't state which Laravel version is supported. Check vendor/sikessem/framework/composer.json for illuminate/foundation / laravel/framework constraints before committing. If it says ^10.0 and you're on 11, expect breakage.

0.x semver means breaking minors. v0.5 → v0.11 in ~a year, with release notes that are literally just "Full Changelog" links. Use ~0.11.0 or a hard pin (0.11.1) and upgrade deliberately in a branch. Do not use ^0.11 in production if you can't tolerate surprise breaks within 0.11.x.

PHP 8.4.21+ is not a suggestion. The README flags earlier 8.4.x as buggy. If your host or CI is on 8.4.0–8.4.20, either upgrade or expect flaky failures that are hard to attribute.

Single maintainer, 1 star, 0 dependents. Practical consequences:

• No community answers. grep the vendor source, don't Google.
• Security response time is unknown. Fork or vendor the package into packages/ if it becomes load-bearing.
• Document your own integration in the repo's docs/ so a future dev isn't reverse-engineering it.

Config cache bite. After editing any published config or env: php artisan config:clear (and config:cache in deploy). Stale config caches look like "the framework ignores my settings."

Provider collisions. If the framework registers its own RouteServiceProvider, ExceptionHandler, or middleware, it may shadow Laravel's. Check php artisan route:list and php artisan about against vanilla. Use php artisan tinker → app()->getLoadedProviders() to confirm load order.

Debugging without docs. Add temporary logging at the extension point:

// AppServiceProvider::register() — runs after package providers
logger()->debug('provider order', array_keys(app()->getLoadedProviders()));

Then php artisan serve and watch storage/logs/laravel.log. Also useful: php artisan event:list (if it ships listeners), php artisan schedule:list, php artisan db:show (if it ships migrations).

Extension points to prefer.

• Publish + edit config before touching source.
• Bind/override in your own provider rather than subclassing vendor classes — Laravel's container makes this clean:

$this->app->bind(
    \Sikessem\Framework\...\Contract::class,
    \App\Sikessem\MyImplementation::class,
);

• Laravel-native extension (middleware, Blade components, macros, events) over forking the package.

Rollback plan. Keep the framework behind a config flag and behind a composer.lock you can git revert. If it overrides core behavior (Eloquent, routing, auth), plan the un-install cost before adoption — removing a service provider is easy; removing assumptions baked into 50 controllers is not.

Migration hygiene. If the package (or its starter) ships migrations, run php artisan migrate --pretend first to see what it touches. Check for table name collisions with your existing schema (php artisan db:show).