Ghygen Laravel Package

Getting Started

ghygen is a scaffolding tool, not a runtime dependency: it renders a .github/workflows/*.yml file for you (Laravel CI: PHP matrix, composer caching, php artisan test, npm build, code-quality/security steps) and you commit the YAML. Plan to install it in require-dev, generate once, and possibly remove it afterwards.

Minimal path:

composer require --dev hi-folks/gh-actions-yaml-generator
php artisan ghygen:install          # publishes config + routes
php artisan serve
# open http://127.0.0.1:8000/ghygen

Where to look first:

1. The generated config/ghygen.php — every UI toggle maps to a config key; this is the source of truth for what the YAML will contain.
2. The web UI at /ghygen — a form per concern (general/triggers/branches, PHP versions, Laravel version, composer, node, testing, code quality, security, custom steps) with a live YAML preview and a save/download action. As of v1.0.1 the selects cover PHP 8.3, Laravel 11, and Node 20.
3. The preview pane — read the YAML before writing it; never blind-save over an existing workflow.

First use case: a brand-new Laravel 11 project where you want push/pull_request CI on main with a PHP 8.2/8.3 matrix, composer cache, copy .env, key:generate, php artisan test. In v1.0.1 you can pick Laravel 11 + PHP 8.3 + Node 20 directly from the selects instead of hand-editing afterwards. Copy the YAML into .github/workflows/ci.yml, commit, and let CI prove it out.

Implementation Patterns

Generate-then-own. The strongest pattern is: use ghygen as an interactive template engine, commit the output, then treat the YAML as hand-maintained. Keep config/ghygen.php in the repo (or in a .ghygen/ backup) so you can re-enter the UI later and re-render when you add a service container or bump PHP versions.

Preview-first workflow. Iterate in the UI, use the YAML preview to diff mentally against your committed file, and only then write. If you prefer to keep the package, the config file lets you reproduce the exact same YAML on demand — useful on a new branch of the same project.

Start on the modern defaults. With v1.0.1, the first render can be Laravel 11 + PHP 8.3 + Node 20 + actions/checkout@v4 + actions/cache@v4 out of the box. Use that as the baseline; the manual bumping that older versions required is mostly unnecessary now.

One workflow per concern. Generate the CI workflow, but keep separate workflows for deployment, scheduled jobs, or release tagging. Ghygen's strength is the "run tests + static analysis + build assets" slice; forcing deploy logic through the UI's custom-steps field ages poorly.

Matrix and services tuned in the UI, then edited. Typical generated shape:

strategy:
  matrix:
    php: ['8.2', '8.3']
services:
  mysql:
    image: mysql:8
    env:
      MYSQL_DATABASE: test
      MYSQL_ROOT_PASSWORD: password
    ports: ['3306:3306']
    options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=5

Use the UI to get the boilerplate right (health checks, env wiring, shivammathur/setup-php extensions), then refine by hand — e.g. add --parallel, coverage upload, or composer validate --strict.

Bootstrapping a team standard. If you maintain many Laravel repos, configure ghygen once in your "canonical" project, save the output as an internal starter workflow (.github/workflow-templates/ or a shared gist), and copy it into new repos. Ghygen effectively becomes your CI style guide generator.

Custom steps for the last mile. Put things the UI doesn't model — php artisan migrate --force against the service DB, npm run build, vendor/bin/phpstan analyse with your chosen level — into the custom-commands section as explicit run: lines, rather than fighting the toggles.

Gotchas and Tips

• The package metadata is still misleading. The listed description ("skeleton application for the Laravel framework") remains wrong — this is a workflow YAML generator. It still has effectively zero dependents and is a local dev utility, not maintained infrastructure. Your committed YAML carries none of that risk, which is the main reason to generate-and-detach.
• Never expose /ghygen in production. The install publishes routes into your app. Gate them (APP_ENV === 'local'), delete the route registration after generation, or never install outside a throwaway/local environment. Verify the route is absent in php artisan route:list for deployed environments.
• v1.0.1 closes most of the "stale versions" gap — but check the drift direction is right. The release bumps actions/checkout@v4, actions/setup-node@v4, actions/cache@v4, github/codeql-action/upload-sarif@v3, symfonycorp/security-checker-action@v5, and webfactory/[email protected], and adds PHP 8.3 / Laravel 11 / Node 20. These are current as of early 2024, but any generator will drift again. After generating, still glance at @vN tags and confirm ubuntu-latest matches your intent (pin ubuntu-22.04 if you depend on specific libs).
• Laravel 11 changed skeleton defaults. If you pick Laravel 11, double-check the generated key:generate, migrate, and env-file steps still match the slimmed-down 11 skeleton — 11 removed some of the bootstrapping that earlier Laravel versions had by default, and a generator tuned for 10-and-earlier may still assume them. Diff the generated YAML against a known-good Laravel 11 workflow the first time.
• Larastan is now wired at a default level. The "upgrading larastan usage" change means the generated code-quality step runs PHPStan/Larastan with a preset level. If you use a phpstan.neon with a different level, edit the invocation (--level=) or point it at your config; don't assume the defaults match your project.
• Env/key ordering matters. php artisan key:generate fails without .env. Make sure the sequence is cp .env.example .env → key:generate → migrate → test, and that APP_KEY isn't baked into a committed .env file.
• Database config in CI is easy to get subtly wrong. If you use a MySQL service container, the test env must point DB_HOST=127.0.0.1, DB_PORT=3306, and your .env.ci/phpunit.xml must actually be read. Sqlite (DB_CONNECTION=sqlite, touch database/database.sqlite) is simpler for pure unit tests and avoids service-container flakiness.
• Caching needs composer.lock in the cache key. Ghygen's composer cache is typically keyed on composer.lock; if the project has no lock file committed, caching is a no-op or worse, stale. Commit the lock.
• npm install vs npm ci. The generated step may default to install; swap to npm ci for reproducibility and fail-fast behavior.
• Overwrite hazard. Saving from the UI can replace an existing workflow file. Commit or stash before regenerating, then git diff the YAML. Prefer downloading and manually pasting if your workflow has hand-written jobs.
• Re-generation drift. Running the UI again from an old config after you've hand-edited the YAML will silently discard your edits. Decide early: either the config is authoritative (regenerate fully), or the YAML is authoritative (use ghygen only once). Don't mix.
• Extension point is the config file, not code. If the UI lacks a step, don't patch the package — use the custom-steps area or edit the output. Forking a low-velocity generator to add a toggle is a bad trade.
• Debugging failures is ordinary GitHub Actions debugging (act locally, --debug re-run, tmate for interactive shells). Ghygen gives you no runtime visibility — that's expected, and another reason the YAML must be readable and hand-editable.