Weave Code
Castor Laravel Package
jolicode/castor
Castor is a PHP-based task runner and automation tool. Define tasks as simple PHP functions and run them from the CLI, with built-in helpers for common workflows like Docker, SSH, file handling, and process management.
🦫 A lightweight and modern task runner for Automation, CI/CD & DevOps.
Frequently asked questions about Castor
- Is jolicode/castor a Laravel package?
- No. Castor is a standalone PHP task runner, not a Laravel package, so it ships no service provider, facade, or publishable config. You install it as a dev dependency and add a castor.php file at the repository root, which means it sits beside your Laravel application rather than inside it. That makes it a fit for build pipelines, Docker orchestration, release preparation, and code generation, not for anything that needs the Laravel container.
- How do I install Castor in a Laravel project?
- Run composer require --dev jolicode/castor, create a castor.php at the project root, and invoke tasks through vendor/bin/castor. Pin an exact version in composer.json and commit the lockfile, because Castor has shipped breaking changes across its 0.x and 1.x releases. You can also use a self-contained static binary for CI agents without PHP, but standardise on one distribution path to avoid autoloading and PHP version drift.
- Does Castor replace Artisan commands and Laravel Envoy?
- Not automatically. Castor competes for the same automation entry point already covered by Artisan, Composer scripts, and Laravel Envoy, so the fit is strongest for PHP-authored tasks outside the app lifecycle. Use it for Docker workflows, database snapshots, asset builds, and deploy hooks, and let Artisan keep handling anything that needs Eloquent, config, queues, or HTTP bootstrapping. Document the boundary explicitly, otherwise commands get implemented twice and drift.
- What PHP versions and Laravel versions does Castor support?
- Castor requires PHP 8.1 or newer, which matches what modern Laravel applications already run. Because it is not a Laravel package, it is not tied to a Laravel release cycle and will not break when you upgrade the framework. Check the Castor changelog for its own minimum PHP requirement before upgrading, since that can move independently of Laravel.
- How do I define and run a task in Castor?
- You declare a task as a plain PHP function annotated with the #[AsTask] attribute, and Castor executes it through a Symfony Console kernel. Tasks run from the CLI with vendor/bin/castor task:name, and because they are ordinary PHP you can reuse your project's types, autoloading, Symfony HttpClient, and Process component. Wrapping existing php artisan calls or Composer scripts inside a task is straightforward, so adoption can be incremental.
- Can Castor handle Docker, SSH, and file operations?
- Yes. Castor ships built-in helpers for common automation workflows including Docker, SSH, file handling, and process management. That lets you express container orchestration, remote commands, and filesystem tasks as PHP functions instead of shell snippets or Makefile targets. It is the main advantage over Make or Just: no new DSL to learn, just PHP your team already knows.
- Is Castor safe to use in production?
- Castor is a development and automation tool, not a production runtime dependency, so it should stay in require-dev and never be loaded by your application. Its API has moved quickly from 0.x into 1.x with breaking changes to task definitions, context handling, and helper signatures. Pin an exact version, treat upgrades as scheduled work with a changelog review, and keep tasks as thin wrappers so exit costs stay low.
- How do I test Castor tasks in a Laravel CI pipeline?
- Because tasks are plain PHP functions, extract the real logic into testable classes and keep the Castor function as a thin wrapper, then unit test the underlying code as usual. End-to-end confidence comes from running the actual castor commands in CI against a disposable database or container. Avoid putting complex branching inside task definitions, since that logic is only exercised by invoking the CLI.
- What are the best alternatives to Castor for Laravel automation?
- The main alternatives are Artisan commands, Composer scripts, Laravel Envoy, Make, Just, and Taskfile. Artisan and Envoy keep you inside Laravel conventions but are weaker for Docker and cross-project orchestration, while Make and Just are fast but introduce a separate DSL. Castor's pitch is PHP-native automation with dependency awareness, which matters most when your team already lives in PHP.
- Who maintains Castor and how should I handle upgrades and breaking changes?
- Castor is maintained primarily by JoliCode with a modest community following, which is acceptable for a dev-tooling dependency but disqualifies it as anything resembling production infrastructure. Pin the version in composer.json, commit the lockfile, and review the changelog before every bump rather than floating along. Before adopting it, confirm the exit cost: if the project is abandoned, your tasks should be thin enough to port back to Composer scripts in a day.
Weaver
How can I help you explore Laravel packages today?