Weave Code
Runnable Laravel Package
directorytree/runnable
A lightweight Laravel package that lets Eloquent models run their own actions. Add the trait, define runnable methods, and invoke reusable model-specific logic in a clean, testable way instead of scattering it across controllers, jobs, and services. Keeps behavior close to the data it acts on.
Run and fake focused PHP classes using Laravel's container.
Frequently asked questions about Runnable
- What is directorytree/runnable and what problem does it solve in Laravel?
- Runnable is a lightweight Laravel package for invoking focused PHP classes through Laravel's service container and swapping them for fakes in tests. Its overview focuses on Eloquent models that run their own model-specific actions via a trait, keeping behavior close to the data it acts on. The TPM assessment frames it as a convention enabler for one-class-one-job actions and boundary faking rather than a platform dependency.
- How do I install directorytree/runnable in a Laravel app?
- Install it with Composer using composer require directorytree/runnable and pin at least version 1.0.2, because that release fixes fakes being bypassed when a class is resolved with explicit constructor parameters. The package uses Laravel service-provider auto-discovery, so manual provider registration should not be needed in a standard Laravel app. Confirm the Composer constraint and discovery behavior against the README before starting a pilot.
- Does Runnable support Eloquent models running their own actions?
- The package overview says yes: you add the trait to an Eloquent model, define runnable methods, and invoke reusable model-specific logic instead of scattering it across controllers, jobs, and services. The technical assessment describes the same seam more generally as container-resolved focused classes, so verify the exact trait and method names in the README. If your use case is purely model behavior with no container seam, evaluate whether the trait adds enough value over plain methods.
- Which Laravel and PHP versions does Runnable support?
- The provided context does not specify a supported PHP or Laravel version matrix, and that is a key question to resolve before adoption. Ask the maintainer which versions are tested in CI and confirm the Composer constraint before your pilot. Do not assume coverage for older Laravel releases, new PHP versions, or Octane and long-running workers without verification.
- How do I fake a runnable class in PHPUnit or Pest tests?
- Register the package's fake in your PHPUnit or Pest test setup, then resolve the runnable class through the container so the fake is returned at the boundary. Pin 1.0.2 or later, because earlier behavior could silently bypass fakes when a class was resolved with explicit constructor parameters such as app()->make(Action::class, ['dependency' => $dep]). Keep fakes scoped to individual tests and confirm that fake state does not leak under parallel execution.
- Does Runnable work with queued jobs, method injection, and Laravel Octane?
- That is not confirmed in the provided context. The assessment explicitly lists make, call, method injection, queued jobs, and Octane as paths whose fake-resolution behavior needs testing, and it flags resolution semantics under Octane and long-running queue workers as a concrete risk. Run a small compatibility spike for each invocation path you rely on before standardizing on the package.
- Is directorytree/runnable safe to use in production?
- Treat it as a dev and test dependency first, and do not make it a runtime dependency until it has earned that in a bounded pilot. Technical risk is low, but supply-chain and ownership risk are moderate: the package has 11 stars, 0 dependents, a single-org maintainer, no commercial support, and no third-party production validation. MIT licensing gives you a fork or vendor escape hatch, but exercising it turns a one-line dependency into an owned internal asset.
- How does Runnable handle constructor dependencies and container bindings?
- Runnable is designed around Laravel's container, so constructor dependencies are resolved the same way they are for other container-resolved classes. The 1.0.2 fix specifically addresses explicit constructor parameters being passed at resolution time, which is a common Laravel idiom. The context does not confirm behavior for contextual bindings, interface bindings, unions, or nested dependencies, so test those cases explicitly.
- Can I use Runnable with Mockery and parallel test runners?
- The package is intended to compose with PHPUnit and Pest-style testing, and the assessment calls out Mockery and parallel test runners as questions to validate. The main risk is fake state leaking across tests, especially under parallel execution, so isolate fake registration and reset container state between tests. Keep existing interfaces or thin adapters so call sites remain reversible if you need to remove the package.
- What are the alternatives to Runnable, and when should I avoid it?
- Alternatives are plain container-resolved action classes with hand-rolled fakes, Laravel job-level faking, Mockery-based mocks, or your own action and fake convention; Runnable mainly standardizes a seam you already have. Avoid it for non-Laravel PHP, service-locator-heavy legacy code, or queue and event-first architectures where job-level faking already covers the testing need. Also avoid adopting it without test discipline, because the package does not create the seam by itself.
Weaver
How can I help you explore Laravel packages today?