Platform Bundle Laravel Package

Getting Started

This release is documentation- and scaffolding-focused (README rewrite for sync_db, refreshed Platform.sh example files behind the init command, composer.json touch-ups), so there's no new API surface to learn — but it is the right moment to (re)run the scaffolding on existing projects.

1. Install and inspect the constraints first. Run composer require platformsh/laravel-bridge (confirm the exact vendor/name in the 1.0 composer.json — the package has been renamed before), then check what it pinned for PHP and laravel/framework before committing the lock file.
2. Publish the config. php artisan vendor:publish and open config/platformsh.php. This is the file that maps a Platform.sh relationship name → Laravel connection/service config. Read it top to bottom before touching anything else; most "it doesn't work" reports start here.
3. Run the init command. php artisan platformsh:init (confirm the signature with php artisan list) writes the .platform.app.yaml, platform/services.yaml and platform/routes.yaml examples into your project. Diff them against anything you already have rather than accepting them blindly.
4. First real use case: make php artisan migrate work unchanged locally and on the platform. Locally the bridge should fall through to .env; on Platform.sh it should read PLATFORM_RELATIONSHIPS and populate the DB config. Verify both paths before adding anything else (Redis, queues, search).
5. Seed local data using the sync_db flow the README now documents — pull a database down from an environment instead of hand-rolling dumps.

Implementation Patterns

One config path, two environments. The idiomatic pattern is: never branch on app()->environment() for infrastructure. Let the bridge resolve relationships when PLATFORM_APPLICATION is present and fall back to .env otherwise, so config/database.php and config/queue.php stay boring.

Deploy hooks, not runtime. Put php artisan migrate --force, php artisan config:cache, php artisan route:cache and asset compilation in the deploy hook; put composer install --no-dev --optimize-autoloader and frontend builds in the build hook. Anything in web.command.start runs on every container start and should be a no-op.

Map each service once, reuse it three times. A single Redis relationship typically feeds cache, session and queue. Drive all three from platform-provided environment variables (CACHE_DRIVER, SESSION_DRIVER, QUEUE_CONNECTION) set in .platform.app.yaml rather than hard-coding drivers per environment.

Treat the generated YAML as a starting point. After platformsh:init, you almost always need to add: the relationships: entry for your database, mounts: for storage/ and bootstrap/cache, and the correct PHP version / web.command.start for your runtime. Commit the generated files as a reviewed diff, not as a blind git add -A.

Refresh after upgrading. Because 1.0 ships newer example files, re-running the init command on a project created with an older version is a low-cost way to pick up changed .platform.app.yaml defaults — do it on a branch and diff.

Multi-app projects. Each Laravel app gets its own .platform.app.yaml and its own relationship set; don't assume the bridge's default relationship names map cleanly when you have two apps in one project.

Gotchas and Tips

• sync_db is a CLI command, not an Artisan command. The 1.0 README clarifies this, but it's still the most common confusion — you run it via the Platform.sh CLI from your local machine, not via php artisan.
• The init command may clobber customized YAML. Back up or commit your existing .platform.app.yaml / services files first; the "latest example files" are generic and won't know about your mounts, workers or cron.
• PLATFORM_RELATIONSHIPS is base64-encoded JSON. If you ever hand-roll a resolver instead of using the bridge, decode then json_decode — attempting to parse the raw value is a classic silent failure.
• Relationship name mismatch fails quietly. A typo in the relationship name usually means the config falls back to .env defaults, and you get a connection-refused at runtime rather than a clear error. Debug with platform ssh then env | grep PLATFORM and compare against config/platformsh.php.
• Read-only filesystem. Writes outside declared mounts fail at runtime, and Laravel writes to storage/ and bootstrap/cache constantly. This is the single most common first-deploy failure.
• Config caching timing. Caching config during build bakes in values that don't exist yet; relationships are only available at runtime. Prefer runtime resolution via the service provider, or cache in deploy after relationships exist.
• composer.json changes can move your framework version. After this release, run composer update --lock platformsh/* deliberately and read the diff — a widened or narrowed constraint can change the resolved Laravel version in CI without any code change on your side.
• Extension points are thin by design. Customization mostly lives in the published config (adding service types, renaming mappings) or by binding your own relationship resolver in a service provider; the package intentionally doesn't wrap the whole Platform.sh API, so don't expect helpers for every service.