Api Platform Extra Laravel Package

Getting Started

This release (v0.2.0) changes two things that affect day-to-day use: the Symfony (SF) floor is now 4.4 with 5.x support, and every configuration option is opt-in. Treat it as a deliberate configuration-first upgrade, not a drop-in patch.

1. Check framework alignment before installing. The SF 4.4 / 5.x requirement maps to Laravel 6.x and newer in practice. If you are on an older Laravel whose Symfony components are below 4.4, Composer will either block the upgrade or you will hit runtime incompatibilities. Run composer why symfony/http-foundation (or the relevant SF component) and confirm you are on a supported line.
2. Publish and read the config file first. The package’s behaviour is now controlled entirely by explicit flags. Run php artisan vendor:publish --tag=<package-config> (check the README for the exact tag), then read every enabled key before touching application code. The config file is now the primary documentation.
3. Enable one feature at a time. Pick the smallest useful feature — typically a middleware, route macro, or service binding — set its flag to true, and verify it with a smoke route or Artisan command. Do not enable everything at once; opt-in defaults mean “off” is the safe state, and you want to see each feature switch on cleanly.
4. First use case: enable the package’s core integration in config/<package>.php, clear config cache, and hit a test route. If nothing happens, that is expected in v0.2.0 — the feature is almost certainly still disabled or cached.

Where to look first: the package README’s configuration section, the published config file’s enabled keys, and the package service provider to see which registrations are guarded by those flags.

Implementation Patterns

Explicit flags per environment. Because all configuration is opt-in, use environment variables with false defaults and enable features deliberately in each environment. For example:

// config/<package>.php
'features' => [
    'middleware' => env('<PACKAGE>_MIDDLEWARE_ENABLED', false),
    'routes'     => env('<PACKAGE>_ROUTES_ENABLED', false),
],

This makes local and production behaviour explicit and reviewable in pull requests.

Feature-by-feature rollout. Enable one block, run the test suite, commit, then enable the next. The opt-in model is designed for this. It also makes rollback trivial: flip the flag to false rather than reverting code.

Test setup must enable features. A common failure mode with opt-in config is tests that silently pass because the feature is off. In tests/TestCase.php, enable the specific features each test needs:

protected function setUp(): void
{
    parent::setUp();

    config([
        '<package>.features.middleware' => true,
        '<package>.features.routes' => true,
    ]);
}

Add at least one assertion that proves the feature is active — for example, that the route returns the package’s expected response, not a 404.

Upgrade pattern from v0.1.x. Do not assume your published config matches the new stub. Diff your existing config against the fresh v0.2.0 stub in a scratch directory, then port over only the enabled flags you actually need. Keep the diff in the pull request so reviewers can see which behaviours were switched on intentionally.

Composition and extension. If the package exposes Symfony-based services, bind your own implementations after the package’s service provider registers. Check whether the provider uses register() and boot() conditionally; opt-in flags often guard boot() registrations such as middleware, routes, or view namespaces. Use the package’s documented extension points rather than overriding internals.

Production config discipline. Treat the package config as code: commit it, review it, and cache it. In deployment, run php artisan config:cache after environment variables are set. In local development, run php artisan config:clear whenever you toggle a flag.

Gotchas and Tips

• Silent no-ops are the main risk. With all configuration opt-in, a forgotten flag does not throw an exception — the feature simply does nothing. Add a boot-time log line or a health-check assertion when a feature is enabled so you can distinguish “off” from “broken.”
• Stale config cache. The most common “I enabled it but nothing changed” cause is cached config. Run php artisan config:clear locally and rebuild the cache in production after flag changes.
• Symfony version mismatch. v0.2.0 requires SF 4.4+ and supports 5.x. If Composer resolves an older SF component, you will get confusing runtime errors rather than a clean failure. Pin the package version ("vendor/package": "0.2.*") and verify the resolved Symfony versions with composer show symfony/http-foundation before deploying.
• Old published config can mask the breaking change. If your v0.1.x config had features enabled by default, upgrading the package code without republishing leaves those old defaults in place. That can make the opt-in change appear to have no effect in one environment while a fresh install behaves differently. Normalise the config across all environments.
• Check what the opt-in flag actually guards. Some flags may control service bindings, others middleware, routes, or migrations. Enabling a top-level flag may not enable its dependencies; read the provider’s conditional blocks rather than guessing from the config key name.
• Debugging: dump the resolved config with config('<package>') in a temporary route or php artisan tinker; inspect the package’s log channel in storage/logs/laravel.log; and confirm middleware order if the package registers global or group middleware.
• Extension points: publish only the assets, views, or migrations for features you have enabled. With opt-in configuration, publishing everything creates dead files and makes it harder to see what is actually active.
• Version pinning: this is a 0.x release with a breaking configuration semantic change. Pin to 0.2.*, read the 0.3 release notes before upgrading, and keep a short internal note of which flags your application depends on.