Weave Code
Talon Laravel Package
phalcon/talon
Phalcon Talon is a framework-neutral test harness and bootstrapping toolkit for Phalcon projects. It provides reusable traits, extendable PHPUnit base classes, and a one-line bootstrap, so unit, integration, and functional tests need minimal boilerplate. Requires PHP 8.1+ and Phalcon 5 or 6.
Test harness and Phalcon bootstrapping for PHPUnit and beyond
Frequently asked questions about Talon
- What is phalcon/talon and what problem does it solve?
- Phalcon Talon is a test harness and bootstrapping toolkit for Phalcon projects. It ships framework-neutral traits as its core, ready-to-extend PHPUnit base classes, and a one-line bootstrap so unit, integration, and functional tests need minimal boilerplate. Instead of writing the same DI container setup, service registration, and reflection helpers in every project, you install Talon once and extend its base test cases.
- How do I install phalcon/talon in a Phalcon project?
- Install it with Composer as a dev dependency: composer require --dev phalcon/talon. Then create tests/bootstrap.php, require vendor/autoload.php, and call Talon::boot(Settings::fromEnv()). Point PHPUnit at that bootstrap file in phpunit.xml and your test suite is ready to run.
- Does phalcon/talon work with Laravel applications?
- No. Talon is built specifically around Phalcon bootstrapping: its Settings and bootstrap stages assume a Phalcon application, DI container, and directory layout. Laravel projects should use Laravel's own testing helpers such as RefreshDatabase and the base TestCase, which cover the same ground for that framework. The framework-neutral traits are the only piece that is conceptually portable, but the harness itself is not a Laravel package.
- Which PHP and Phalcon versions does phalcon/talon support?
- Talon requires PHP 8.1 or newer. It works with either the ext-phalcon C extension at version 5 or the phalcon/phalcon pure PHP implementation at version 6, and it automatically detects whichever one is present. That means you can run the same test suite on a traditional extension install or on a Composer-only Phalcon setup.
- Do I need the Phalcon extension installed to run Talon tests?
- Not necessarily. Talon detects whether ext-phalcon 5 or the phalcon/phalcon 6 PHP implementation is available and adapts to it. This is useful in CI images or containers where compiling the C extension is inconvenient, since you can install phalcon/phalcon via Composer instead. Talon also provides a helper such as checkExtensionIsLoaded where a test genuinely needs to assert extension presence.
- Should phalcon/talon be a dev dependency or a production requirement?
- Install it with the --dev flag, since it is a test harness and not part of your application runtime. Keeping it in require-dev means Composer's production install with --no-dev will not ship test traits and base classes to your servers. Your application code should never depend on Talon classes outside of the tests directory.
- How does the one-line bootstrap work and how do I add setup hooks?
- The simplest form is Talon::boot(Settings::fromEnv()), which reads configuration from the environment and prepares the Phalcon application for tests. If you need the equivalent of the old loadIni or loadFolders hooks, use the bootstrap runner instead: Runner::for(Settings::fromArray(['root' => __DIR__ . '/..'])) and chain before(Stage::Environment, ...) or after(Stage::Directories, ...) callbacks before calling boot(). Each callback receives the Settings object, so you can set ini values, create output directories, or register extra services at the right point in the sequence.
- What helpers does AbstractUnitTestCase give me for testing protected methods?
- AbstractUnitTestCase exposes callProtectedMethod, getProtectedProperty, setProtectedProperty, and invokeMethod so you can exercise non-public code without writing reflection boilerplate in every test. For filesystem assertions it adds getNewFileName, safeDeleteFile, safeDeleteDirectory, and assertFileContentsContains. Combined with the integration and functional base classes plus the underlying traits, this covers most of the repetitive setup in a Phalcon test suite.
- How do I configure Talon settings and output paths for my project?
- Use Settings::fromEnv() to pull configuration from environment variables, or Settings::fromArray with keys such as root to point Talon at your project directory explicitly. Settings also resolves output locations, for example outputPath('screens'), which you can create in a Stage::Directories hook. This keeps paths consistent between local runs and CI without hardcoding them in each test class.
- Is phalcon/talon actively maintained, and what are the alternatives?
- Talon is an official part of the Phalcon ecosystem, published on Packagist with CI, static analysis and coverage reporting, and it is released under the permissive BSD-3-Clause license. It is actively versioned alongside Phalcon 5 and 6, so pin a compatible major version in composer.json and review the changelog when upgrading. Alternatives include writing your own PHPUnit bootstrap and DI wiring, Phalcon's incubator testing helpers, or full-stack tools such as Codeception, but all of them require more boilerplate than extending Talon's base test cases.
Weaver
How can I help you explore Laravel packages today?