Post Install Laravel Package

Getting Started

ibexa/post-install is not a runtime library — it is a reference scaffolding package. It ships the canonical Cloud/Platform.sh configuration (.platform.app.yaml, .platform/services.yaml, .platform/routes.yaml), PHP-FPM/nginx vhost templates, Fastly VCL snippets, Solr schema additions, and the non-interactive wiring for ibexa:install. Day to day you consume it as a source of truth to copy into your project, not as an API you call.

Minimal steps:

1. Check whether it is already in your tree. In a standard Ibexa DXP / Ibexa Cloud project it arrives transitively (ibexa/cloud or the Cloud metapackage pulls it in). Run composer show ibexa/post-install before adding it explicitly.
2. Add it only if you are targeting Ibexa Cloud. composer require --dev ibexa/post-install:^5.0 (or ^4.6 to match your DXP line — see Gotchas). For on-prem/self-hosted Docker deployments this package has little to offer beyond vhost templates.
3. Look at vendor/ibexa/post-install/ first, specifically the .platform/ directory, the vcl/ (Fastly) directory, and the solr/ schema files. The README is a license header only — the actual documentation is the file tree itself plus the GitHub release notes.
4. Diff, don't blindly copy. Compare vendor/ibexa/post-install/.platform.app.yaml against your project-root .platform.app.yaml and merge the deltas you actually need (PHP extensions, display_errors, Node version, hooks).
5. First real use case: getting a fresh Ibexa Cloud environment to build and deploy — .platform.app.yaml build hook (composer install, php bin/console ibexa:install --no-interaction, asset build), deploy hook (cache clear, migrations), plus services.yaml for the database, Solr, and Redis.

The one command that matters: ibexa:install in non-interactive mode (--no-interaction), which the Cloud build hook invokes. Everything else is file plumbing.

Implementation Patterns

Baseline-then-override (most common). Copy the platform files into the repo root, commit them, and treat vendor/ibexa/post-install/ as read-only upstream. Every DXP upgrade becomes: composer update ibexa/post-install, then diff -ru vendor/ibexa/post-install/.platform .platform to see what upstream changed. This is the single highest-value habit with this package — the changelog is full of config-level fixes (compression rules, Solr fields, PHP extensions) that silently matter in production.

Config drift detection in CI. Add a job that diffs your committed .platform/*.yaml and vcl/*.vcl against the vendor copies and fails (or warns) on divergence. Because release notes are so often "no significant changes," drift is invisible until something breaks in a deploy.

Deploy hook composition. Typical structure for .platform.app.yaml:

hooks:
  build: |
    set -e
    composer install --no-dev --no-progress --prefer-dist --optimize-autoloader
    php bin/console ibexa:install --no-interaction
    npm ci && npm run build
  deploy: |
    set -e
    php bin/console cache:clear
    php bin/console doctrine:migrations:migrate --no-interaction

Keep project-specific steps below the upstream block so rebasing on a new post-install release is a clean merge rather than a rewrite.

Fastly/VCL layering. The package's VCL snippets encode rules you would not guess: exclude api and json from compression, the Ibexa cookie handling rule (restored in IBX-8885), and the session prefix rebrand (IBX-8811). If you maintain custom VCL, add your snippets after the upstream ones and be aware upstream renames files across majors (the v5 changelog is full of ibexa-* rebranding from ezplatform-*).

Solr schema as a versioned artifact. The Solr schema lives with this package, and it has historically lagged (missing random_* fields, IBX-7806). Copy the schema into your own Solr config directory, own it, and reindex when you bump. Do not point Solr at vendor/ paths — composer update will change them under you.

Spell-check / lint scaffolding. The package includes spell-checking support (IBX-6649). If your team runs cspell/typos in CI, borrow the dictionary and ignore-list rather than building your own — it is pre-tuned for Ibexa terminology (SiteAccess, ContentType, FieldType).

Environment parity for local Docker. The vhost templates were copied from the Ibexa Docker repo (IBX-3465). If you run Docker Compose locally and Platform.sh in staging/prod, use the same vhost templates from this package in both places to avoid "works locally, 502 in staging" nginx discrepancies.

Gotchas and Tips

The license is the biggest non-technical trap. GitHub reports NOASSERTION because the package is dual-licensed: Ibexa Business Use License (requires a paid DXP subscription) or GPL-2.0. If you are on the open-source edition, you are on the GPL branch — which means copyleft obligations for anything you distribute. Confirm with legal before shipping a product that vendors these files; copied config templates may or may not be considered derivative.

Version alignment is mandatory. Branch 4.6.x and 5.x track the DXP majors and are not cross-compatible (Symfony 6 vs 7, Node 18 vs 22, ezplatform vs ibexa naming). Pinning ^5.0 into a 4.6 project produces files that reference services and env vars that do not exist in your runtime. Pin to the same minor line as ibexa/*.

Never edit inside vendor/. Obvious, but the failure mode is subtle: a hotfixed .platform.app.yaml in vendor works locally and vanishes on the next composer install. The vendor copy must be treated as immutable upstream.

IbexaSetupCommand is deprecated (v5.0.7, IBX-11474) in favor of an ibexa/cloud package-existence check. If you have custom scripts calling it by class name, they will break in a future major — migrate to checking for the ibexa/cloud package or to the CLI command name.

Deployment flow changed in v5 (IBX-9942): the process moved to the Symfony Cloud configurator and symfony-deploy. Projects with hand-rolled deploy scripts copied from an older post-install will find the hooks no longer match the documented flow. Re-read the upstream .platform.app.yaml on every major bump rather than assuming your old copy is still valid.

display_errors is disabled in Cloud (IBX-8506). This is correct for production but makes local debugging of a Cloud-like environment painful — you will get blank 500s. Keep a local .platform.app.yaml override with display_errors: On, and rely on var/log/ in Cloud.

Long URLs and direct index.php access were a real bug (IBX-7818, fixed via vhost/rewrite changes). If you self-host with your own nginx config, port that fix or you will hit the same issue with very long request URIs.

Session prefix was rebranded (IBX-8811). Upgrading an existing deployment can invalidate all active sessions and orphan existing cookie names. Schedule it — it is not a hot-patchable change.

ibexa:install must be non-interactive in build hooks. Without --no-interaction it will hang the build until the Platform.sh build timeout. This was explicitly adjusted upstream (IBX-9898); if you copied an older hook, it may still prompt.

Debugging a failed deploy: check the build hook log first, not the application log. The vast majority of failures are ibexa:install (DB not reachable in build — it should be a deploy-hook concern, not build), missing PHP extension (sodium was famously missing from the OSS edition config, IBX-2919), or Node version mismatch.

Extension points are files, not classes. There is essentially no PHP API surface to hook into beyond the install command. Your integration surface is: the YAML hooks, the vhost templates, the VCL snippets, and the Solr schema. Plan customization accordingly — you are forking config, so keep a clear diff against upstream.

Zero dependents and 8 stars is a signal, not a red flag. This package is only ever installed transitively by Ibexa Cloud projects, so the star count tells you nothing about quality. But it does mean there is no community documentation: your best "docs" are the pull request titles in the release notes, which are detailed and describe the exact operational change.