Castor Symfony Laravel Package

Getting Started

Castor-symfony is a Castor task library that scaffolds local virtual hosts for Symfony (and by extension Laravel) projects. If you are picking it up fresh at V2.0, be aware that this is a major release with a breaking change: vhosts generated by the package no longer come pre-populated with the default "concerns" that older versions injected (SSL blocks, logging, PHP-FPM handlers, and similar defaults). What you get now is a clean, minimal vhost skeleton that you are expected to extend yourself.

Start here:

1. Read the V1 → V2 changelog first. The single PR (#6, "Delete all concerns from created vhost") is the only substantive change, and it defines the entire upgrade path. If you were on V1.1.3, treat any vhost config you relied on as gone unless you re-add it.
2. Run castor list (or your project's equivalent) to see the task namespace the package registers. This tells you what vhost lifecycle commands are exposed.
3. Generate a throwaway vhost against a test project and diff it against a V1 vhost (or your existing /etc/hosts + server config) to see exactly which blocks are now missing.
4. First real use case: point the package at a fresh Laravel app, create the vhost, confirm it serves public/index.php over HTTP, then re-add the concerns you actually need (TLS, logging, FastCGI) as your own templates or Castor tasks.

Implementation Patterns

Treat generated vhosts as a starting point, not a finished artifact. The central V2.0 workflow is: generate the minimal vhost, then layer your own configuration on top.

• Template/concern layering. Since default concerns were stripped, adopt an explicit composition pattern. Keep your own reusable snippets (SSL, access/error logs, fastcgi_pass, try_files, gzip) in a project directory and concatenate them into the generated vhost as part of your Castor task rather than expecting the package to inject them.
• Per-project configuration. Drive the package via your castor.php so vhost parameters (hostname, document root, PHP socket path, backend port) are explicit and version-controlled alongside the app. This insulates you from future releases changing defaults again.
• Idempotent create/recreate tasks. Wrap "create vhost" in a task that removes the previous file first, since a bare vhost from V2.0 plus your overlays means partial state is easy to accumulate. Always regenerate rather than patch in place.
• Local-dev bootstrap. Chain tasks: castor vhost:create → add hosts entry → restart the web server → smoke-test the URL. Because the concerns are gone, your chain must now include whatever step previously handled TLS/logging setup.
• Laravel integration tip. Point the document root at public/, map try_files $uri $uri/ /index.php?$query_string yourself, and set the FastCGI handler for index.php — none of that is guaranteed by the package anymore.

Gotchas and Tips

• V2.0 is the breaking change. The single changelog line ("Delete all concerns from created vhost") means upgrades from V1.1.3 will silently produce different, emptier vhosts. If you have automation that assumes SSL/logging/FastCGI blocks are present, it will break without an obvious error — the vhost simply won't behave as before.
• No default SSL. If your old workflow relied on the package injecting a TLS listener or certificate paths, you must add them manually. Expect plain HTTP and browser "not secure" warnings until you do.
• Silent success, missing behavior. Vhost creation will still "succeed" — it just writes less. Debug by diffing the generated file against your expectations, not by looking for task failures.
• Logging gaps. Access/error log directives may no longer exist. If your debugging workflow tailed a vhost-specific log, check the web server's global error log instead until you re-add log concerns.
• FastCGI/PHP handler must be verified. The lack of concerns likely includes the PHP-FPM handler. A blank page or 502 after generation is the tell — inspect the vhost for fastcgi_pass / proxy_pass and add it if missing.
• Pin your version. Because V2.0 removes functionality, pin ~1.1.3 if you want the old behavior while you migrate, and pin ^2.0 deliberately once your own concern overlays are in place. Avoid * constraints.
• Extension point: your own Castor tasks. The cleanest path forward is to stop depending on package-provided concerns entirely and own a castor/concerns/ directory of snippets that you compose into the generated vhost. This is future-proof and makes the package's vhost generation a thin helper rather than a config authority.
• Watch for follow-up releases. A major version whose only change is deleting concerns often signals a redesign in progress. Re-check the changelog before upgrading again — the concern model may return in a different form (e.g. opt-in flags or a plugin system).