Archer Laravel Package

Getting Started

Archer is not a Laravel package. It is a convention-driven CLI tool for PHP project testing, CI, and documentation. For a Laravel developer, its day-to-day leverage is low: use it only when maintaining a standalone PHP library or a legacy Icecave-style package, not inside a modern Laravel application.

Minimal steps:

1. Inspect before installing:
   • vendor/icecave/archer/README.md
   • vendor/icecave/archer/composer.json
   • vendor/bin/archer --help
2. Attempt installation only in a dev-only context:

   composer require --dev icecave/archer
   

   If Composer reports PHP or PHPUnit conflicts, stop there. Do not force it into a Laravel app.
3. Confirm the executable and available commands:

   vendor/bin/archer --help
   

4. Add an isolated Composer script, not a replacement for Laravel’s test command:

   {
     "scripts": {
       "test": "php artisan test",
       "test:archer": "archer test"
     }
   }
   

First useful use case: a small standalone Composer package with a conventional src/ and test layout, where you want one command to run tests and generate API documentation in CI. For a Laravel app, your first use case should remain php artisan test with PHPUnit or Pest.

Implementation Patterns

• Keep Archer outside the Laravel application lifecycle. It does not provide a service provider, facade, config file, migrations, or publishable assets. Registering it in config/app.php is meaningless.
• Do not replace Laravel’s test runner. Laravel tests depend on application bootstrapping, environment loading, database refreshes, factories, HTTP testing, queues, and events. Archer will not replace php artisan test.
• Use it for standalone packages only. If you maintain a Composer library that is not a Laravel package, Archer can be a convention-based wrapper around test execution and documentation generation. Verify its expectations against your src/ and test/ layout before adopting it.
• Namespace Composer scripts. Keep Laravel and legacy workflows separate:

  {
    "scripts": {
      "test": "php artisan test",
      "test:legacy": "archer test",
      "docs:legacy": "archer docs"
    }
  }
  

• Isolate it in CI. Add a separate CI job for the legacy package or library instead of injecting Archer into the Laravel application’s main test job. This prevents a broken or abandoned tool from blocking normal Laravel delivery.
• Prefer Archer as a convention checklist. The useful idea is “tests, CI, and docs live in predictable places and run through one command.” You can copy that principle into Laravel with Pint, PHPStan, Pest/PHPUnit, and GitHub Actions without depending on Archer.
• Treat generated documentation as a build artifact. If Archer generates docs, publish them only when the project already does so. Otherwise keep them out of source control and let CI produce them.
• Wrap, don’t patch. If the convention does not fit, create a small Composer script or Make target around Archer. Avoid editing files under vendor/ or forking unless you are prepared to maintain the fork.

Gotchas and Tips

• No community validation. The package has no stars and no dependents in the supplied metadata. Treat it as abandoned or legacy until proven otherwise.
• High risk of dependency conflicts. Archer is likely tied to older PHP and PHPUnit versions. Run composer why-not icecave/archer and check against Laravel 10/11, PHP 8.x, and modern PHPUnit.
• Convention over configuration can fight Laravel. Laravel expects tests/Feature, tests/Unit, phpunit.xml, Artisan bootstrapping, and Pest conventions. Archer may expect a different layout, so do not assume it can discover Laravel tests correctly.
• No Laravel integration points. There is no service provider, facade, config publishing, or Laravel-specific documentation. Any integration is shell/Composer-level only.
• Coverage and docs may require extra extensions. Code coverage typically needs Xdebug or PCOV. Documentation generation may depend on old phpDocumentor or template tooling. Check CI logs carefully.
• Debug by bisecting the underlying tools. If archer test fails, run vendor/bin/phpunit directly. If docs fail, inspect the generated command or source under vendor/icecave/archer/src. Use --help on the Archer binary before guessing command names.
• Keep it dev-only. Never require Archer in production. Deploy with composer install --no-dev, and pin the PHP platform in composer.json if you must keep a legacy CI job stable.
• Do not make it the default test script. In a Laravel project, that would bypass php artisan test. Reserve archer test for an explicitly named legacy workflow.
• Re-evaluate the need. For new Laravel work, use Artisan, PHPUnit/Pest, Pint, PHPStan or Larastan, and GitHub Actions directly. Archer’s only practical value here is as a legacy compatibility tool or a reminder to keep project conventions consistent.