What the agent does
The agent reads what the starter gives it. In an app laid out like codeigniter4/appstarter, composer.json requires php ^8.2 and codeigniter4/framework ^4.7, with phpunit ^10.5.16, fakerphp/faker and mikey179/vfsstream for development. app/Config/Routes.php has one route, $routes->get('/', 'Home::index'), and app/Controllers/Home.php returns the welcome_message view. app/Config/Validation.php already registers FileRules alongside Rules, FormatRules and CreditCardRules, so the file rules need no setup. app/Config/Filters.php defines a csrf alias but leaves it commented out of $globals, and app/Config/Security.php sets $csrfProtection = 'cookie'. writable/uploads/ exists with only an index.html. phpunit.dist.xml bootstraps the framework's test harness with app.baseURL set to http://example.com/, and .github/workflows/phpunit.yml runs vendor/bin/phpunit --coverage-text on PHP 8.2 and 8.5.
The feature is an Uploads controller with three actions and a form. GET /uploads renders a view with form_open_multipart('uploads'), which also emits the CSRF field; POST /uploads validates with the file rules that read from the request rather than from $_POST: uploaded[attachment], max_size[attachment,2048], ext_in[attachment,png,jpg,jpeg,pdf] and mime_in[attachment,image/png,image/jpeg,application/pdf]. The controller then takes $this->request->getFile('attachment'), checks isValid() and ! hasMoved(), and moves it with move(WRITEPATH . 'uploads', $file->getRandomName()), because the client's name is untrusted and getRandomName keeps only an extension. It records the random name, the original getClientName(), the server-side getMimeType() (not getClientMimeType(), which the request supplied) and the size in an uploads table through a CodeIgniter Model with a migration under app/Database/Migrations. GET /uploads/{id} streams the file back with $this->response->download($path, null)->setFileName($originalName), so the files never sit under public/ and nothing in writable/ is ever executed.
CSRF is applied where it matters without turning it on for the whole app: the POST route is declared with ['filter' => 'csrf'], so the token the multipart form helper emits is checked on submit while every other route stays as the starter left it. The agent also adds UPLOADS_MAX_KB to env with a matching app/Config/Uploads.php so the size limit is one setting, and points out in the README that PHP's own upload_max_filesize and post_max_size cap it from below.
Tests follow the starter's tests/ layout. A feature test with FeatureTestTrait requests GET /uploads and asserts the form and the CSRF field are in the page, and posts to /uploads with no file and asserts the uploaded rule's error is shown, with a database test using DatabaseTestTrait and the migration for the model. PHP's is_uploaded_file refuses any file that did not arrive through an HTTP request, so the move cannot be driven from PHPUnit; the agent covers it by starting php spark serve in its sandbox and posting a PNG and an oversized file with curl -F, and quotes both responses in the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add file uploads to this CodeIgniter 4 app. Read composer.json, app/Config/Routes.php, app/Config/Filters.php, app/Config/Security.php, app/Config/Validation.php, app/Controllers/Home.php, app/Controllers/BaseController.php, phpunit.dist.xml, the tests directory and .github/workflows/phpunit.yml first. Add an Uploads controller with a GET form using form_open_multipart, a POST action validated with the uploaded, max_size, ext_in and mime_in file rules, a move into WRITEPATH/uploads under getRandomName, a migration and model recording the stored name, the client name, the server-detected mime type and the size, and a GET download route that streams the file with its original name. Put the csrf filter on the POST route only. Make the size limit a config value read from env. Write a feature test for the form and the validation failure and a database test for the model; since is_uploaded_file cannot be satisfied from PHPUnit, start php spark serve in the sandbox and upload a real file and an oversized one with curl, quoting both responses. Run vendor/bin/phpunit and open a pull request.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request adds app/Controllers/Uploads.php, app/Models/UploadModel.php, a migration under app/Database/Migrations, app/Config/Uploads.php, two views under app/Views/uploads/, and tests/feature/UploadsTest.php and tests/database/UploadModelTest.php; it changes app/Config/Routes.php, env and the README. Its description quotes the PHPUnit summary and the two curl exchanges from the sandbox: a PNG accepted and listed with its random name, and a file over the limit refused with the max_size message.
A reviewer checks the rule list against what the app should accept (the extensions and MIME types are two lines), that the download route is the only path to the files and that writable/uploads is not reachable through public/, and whether the download route needs an authentication filter before it ships, which the starter has none of.
The home route, the existing tests and the CI workflow are unchanged; the migration is the only step a deployment must run.
Run it on every new app from the starter
A team that starts each service from the same starter wants uploads done the same way in each. A handler on your own server, run when a repository is created from the starter, sends this body to POST /o/{org}/sessions with the new repository in resources and a request_id that is a UUID v5 of the repository's id, so a retried call returns the run already started. Each run opens one pull request, and the key's webhook_url receives run.completed.
On a repository that already has the feature, an automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize runs read-only with a prompt that checks any new file field is validated with mime_in and stored under a generated name, and comments when one is not. The trigger adds the event after the prompt; it substitutes nothing.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Upload handling is where a wrong default becomes a security report: a client-supplied name used as a path, a MIME type taken from the request, a file written under public/. The agent writes the version the framework's own uploaded-files guide describes and proves the two halves differently, PHPUnit for validation and the model, and a real multipart request against php spark serve for the move that is_uploaded_file guards, with both outputs kept in the run's record.
It also runs the full suite on the PHP version the sandbox has and reports it, so the reviewer reads one pull request with the commands and their output, not a description of what was tried on a laptop.
Frequently asked questions
Why can't PHPUnit test the actual move?
UploadedFile::isValid() calls PHP's is_uploaded_file, and move() uses move_uploaded_file; both refuse a file that did not arrive through an HTTP upload. The feature test covers the form, the validation failure and the model; the move is exercised against a running php spark serve with curl, and the pull request quotes that exchange.
Why ext_in and mime_in both?
ext_in checks the name the client sent, which is cheap and catches mistakes; mime_in checks the type CodeIgniter detects from the bytes, which a renamed file cannot fake. The stored record keeps the detected type, and the download route sends that, not the client's.
Where do the files go?
Into writable/uploads/, which the starter creates and which public/index.php never serves. The only way to read one is the download route, so adding an authentication filter to that route later is one line in Routes.php.
Does this turn on CSRF for the whole app?
No. The starter leaves csrf out of the global filters, and the agent keeps it that way; the filter is attached to the POST upload route only. If you later enable it globally the form keeps working, because form_open_multipart already emits the token field.
What limits the size?
The max_size rule, read from the new Uploads config and UPLOADS_MAX_KB in env, limits it in the app. PHP's upload_max_filesize and post_max_size limit it first; a file over those never reaches the controller, so the README names both.
More CodeIgniter jobs
The same job on other stacks
- Add File Uploads to a Livewire Component (Livewire)
- Add File Uploads to a React Router App (React Router)
- Add File Uploads to a Reflex Chat App (Reflex)