Larasupport Laravel Package

Getting Started

Larasupport bridges Laravel's package conventions into Lumen. Reach for it the moment you try to install a Laravel-first package (one that calls config_path(), $app->configPath(), vendor:publish, loadViewsFrom, or ships Artisan commands) into a Lumen app and hit "method does not exist" or silent no-ops.

Install and wire up (one-time, ~5 minutes):

composer require irazasyed/larasupport

Swap the Application class in bootstrap/app.php — this is the single highest-value change, because it restores the path helpers and cache-state methods Lumen omits:

// bootstrap/app.php
$app = new Irazasyed\Larasupport\Application\Application(
    realpath(__DIR__.'/../')
);

Then register the providers you actually need, before any vendor package providers:

$app->register(Irazasyed\Larasupport\Providers\ArtisanServiceProvider::class);
$app->register(Irazasyed\Larasupport\Providers\EventServiceProvider::class);
$app->register(Irazasyed\Larasupport\Providers\RoutingServiceProvider::class);

First use case to validate your setup: pick one package that assumes Laravel (e.g. one that publishes a config file), run php artisan vendor:publish --provider="Vendor\Package\ServiceProvider", and confirm the file lands in config/. If that works, the path helpers and provider bridge are functioning and the rest is incremental.

Where to look first: bootstrap/app.php (Application swap + provider order), then config/ (create it if absent — see Gotchas), then the vendor package's ServiceProvider to see which Laravel APIs it depends on.

Implementation Patterns

1. Letting your own package run on both frameworks. Extend Irazasyed\Larasupport\Providers\PackageServiceProvider (or apply the Lumen service provider trait) instead of Illuminate\Support\ServiceProvider. You keep mergeConfigFrom(), publishes(), loadViewsFrom(), loadTranslationsFrom(), and conditional commands() registration, and the package stops caring which framework boots it.

2. Config bootstrap in Lumen. Lumen doesn't auto-load config/*.php. Pair the config_path() support with explicit loading:

$app->configure('my-package');

Do this after the provider is registered, otherwise mergeConfigFrom() runs against a path that isn't wired yet.

3. Artisan parity for package tooling. With ArtisanServiceProvider registered, vendor:publish, route:list, and the make:* generators become available. Use route:list as your first debugging tool when routes appear missing — it's the fastest way to confirm the routing bridge picked up controller routes.

4. Controller routing. RoutingServiceProvider restores Route::controller(...)-style dispatch that Lumen's router omits. If a package registers controller routes via string notation, this provider is what makes them resolvable.

5. Event discovery. EventServiceProvider approximates Laravel's event/listener auto-discovery. For packages that rely on it, register it explicitly rather than hand-wiring every listener in bootstrap/app.php.

6. Pin and verify path semantics. Since v1.7.1 is a deliberate revert of the config_path() changes introduced in 1.7.0, treat config_path() output as a contract worth asserting in a smoke test:

// routes/web.php or a tinker-style check
throw_unless(str_ends_with(config_path(), '/config'), new RuntimeException(config_path()));

7. Version discipline. Constrain to ^1.7.1 in composer.json. If you shipped anything against 1.7.0's path behavior, that code now needs revisiting — see the regressions referenced in issues #23 and #24.

Gotchas and Tips

• The 1.7.1 revert is the headline. If you adopted 1.7.0 and adapted to its config_path() semantics, remove those adaptations. Conversely, if you pinned 1.7.0 as a workaround for something, retest on 1.7.1 before assuming the fix holds.
• config/ may not exist. config_path() helpfully returns a path to a directory Lumen never created. vendor:publish will then fail confusingly. mkdir config in your scaffold or your provisioning script.
• Provider ordering is load-bearing. Larasupport's providers must be registered before vendor package providers, otherwise the vendor provider calls config_path()/$app->configPath() before the bridge is active.
• Cache-state methods lie in Lumen. configurationIsCached() / routesAreCached() exist for compatibility, but Lumen doesn't run Laravel's cache pipeline. If config silently doesn't load, check whether something is short-circuiting on a "cached" return value.
• Don't subclass the Larasupport Application without calling parent::__construct(). You'll lose the path registration and get null-ish helpers with no error.
• Method collisions on newer Lumen. Some newer Lumen releases backfill helpers themselves; overriding them via the custom Application can produce divergent behavior between environments. Guard by checking method_exists() when you build your own extensions.
• Debugging recipe: get_class(app()) to confirm the Application swap actually took (it's easy to leave the stock Laravel\Lumen\Application line in place), then check method_exists(app(), 'configPath'), then confirm config_path() resolves.

Extension point: the Larasupport Application subclass is the intended seam for adding any other Laravel helper your packages expect — add methods there rather than scattering function_exists shims across your app.