CRM Leads Server

1. Summary

CRM Leads Server is the back end of a small customer-relationship tool. A separate single-page app logs in through it, lists leads by date range, records follow-ups, and manages client accounts. Leads arrive from CallRail, a call-tracking service, through a webhook.

It runs on Laravel 7.20 and PHP 7.2, both unsupported for years. PHP 7.2 stopped receiving security fixes in November 2020 and Laravel 7 in March 2021. The dependency lock file dates from mid-2020 and three of its packages are abandoned by their authors.

The good news is that the application is small and conventional. The automated rewrite tools found no PHP-language breakage in the application code; the work is in the framework and package layers, which are well documented. We recommend moving to PHP 8.4 and Laravel 13 in four stages behind a safety net of behavior-pinning tests, with the old runtime kept alive until the final cutover.

2. What we looked at

• The Git repository: 33 commits from March 2020 to June 2021. The working tree has an untracked IDE folder and one uncommitted change to a front-end component.
• Size: 39 application files (1,680 lines), 4 route files, 14 migrations and seeders, 28 Blade views, 15 config files. About 4,700 lines of PHP in total.
• Dependencies: 64 production and 37 development packages in the lock file.
• Tests: the two example tests that ship with a new Laravel install. Nothing application-specific.
• Build tooling: Laravel Mix 5 with Vue 2.5 scaffolding; no compiled assets committed.
• Not available to us: the production database, the hosting environment, the .env file, and the separate front-end that consumes this API.

3. Dependency health

Direct dependencies only; the 89 transitive packages follow these.

4. What breaks on the target

PHP 7.2 to 8.4

Rector, run with the full PHP 8.3 rule set, proposed changes in 21 files, all of them cosmetic: closure return types, arrow functions, rand() to random_int(). No removed functions, no removed extensions, no dynamic-property or implicit-nullable problems in the application code. PHPStan at level 1 reports 28 issues, of which 24 are missing return statements in empty scaffold methods and facade aliases it cannot see; the real ones are in section 6.

Laravel 7 to 13, release by release

From the official upgrade guides, limited to what this codebase actually touches.

• Laravel 8. The user factory uses the legacy closure style; rewrite as a class or add laravel/legacy-factories. The seeds folder is renamed. Routes use string controller names; keep the namespace property on the route provider or convert to class references. Guzzle 7.
• Laravel 9. Symfony 6 removes the HEADER_X_FORWARDED_ALL constant used in the TrustProxies middleware; switch to the framework's version with explicit headers. Remove the proxy and CORS packages; the framework's own CORS middleware replaces the latter. Swift Mailer becomes Symfony Mailer; both Mailables use only subject and markdown, which are unchanged. Re-publish the mail templates.
• Laravel 10. PHP 8.1 minimum; no application impact beyond the runtime.
• Laravel 11. PHP 8.2 minimum. Sanctum 4: publish its migrations and add three middleware references to its config. The slimmer application structure is optional; the Kernel classes keep working and we keep them. Carbon 3 changes diffIn* results, which this code does not use.
• Laravel 12. The container now honors nullable class defaults; the one middleware with a nullable parameter is untyped and unaffected.
• Laravel 13. PHP 8.3 minimum. The CSRF middleware is renamed PreventRequestForgery and gains request-origin checks using the Sec-Fetch-Site header; the webhook exclusions must be carried over and the SPA's cross-site requests verified against the new check. Session serialization defaults to JSON and cache gains an allow-list for serialized classes; both are config decisions at cutover. PHPUnit 12.

Front-end build

Laravel Mix 5 and Vue 2.5. The SPA that users see is a separate application, so this scaffold only compiles one example component nobody renders. Options: move to Vite, the current Laravel default, or delete the unused scaffold. Vue 2 reached end of life in December 2023.

5. Risk register

6. Findings beyond the upgrade

Found while reading the code. Not included in the migration price; the owner decides what to do with each.

1. Plain-text passwords leave the system.security
   Creating a user sets a plain-password field on the record, returns it in the JSON response, and prints it in the welcome email. Fix: never return or email the password; send a set-password link instead.
2. Lead status is random.data
   Both the bulk import and the webhook assign "New Patient" or "Existing Patient" with a coin flip. A commented-out line shows the intended source, the CallRail tag. Every status in the database today is random.
3. Webhook is unauthenticated.security
   Anyone who knows a profile id can post leads to it. CallRail supports signed webhooks; verify the signature.
4. Database errors are returned to clients in full,security
   exposing SQL and schema details in the error responses of three controllers.
5. A webhook route in the web routes file fails at runtimebug
   because the request class is type-hinted without an import. It appears to be dead code superseded by the API route and should be deleted.
6. Relationship bugs.bug
   The platform's leads relation uses the wrong foreign key, and the profile's user relation is declared in the wrong direction. Neither is called by current code.
7. A personal email address is hard-codedhygiene
   in the listener that forwards webhook leads.
8. Weak password rulesecurity
   on API-created users, minimum 5 characters, versus 8 on self-registration.
9. Repository hygiene.hygiene
   IDE folder untracked, one uncommitted change, no compiled assets, no CI.

Items 1, 3 and 4 are security issues and we recommend fixing them in the same engagement; they add about one day.

7. Test coverage and verification plan

Today: two example tests, no application behavior covered.

Before changing a line, we write characterization tests that pin what the application does now, including its quirks, and run them against the current runtime in a Docker container with PHP 7.4 and the locked dependencies. Then every stage must keep them green on the new runtime.

• Login succeeds with 204 and fails with 403 and the exact error body.
• Users: admin can list, show, create (with profile and welcome email) and update; the JSON shape of the user with its profile; logout revokes tokens.
• Leads: each of the nine date presets returns the expected rows; bulk import from a CallRail payload creates one lead per entry with the start time parsed; status update.
• Follow-ups: creation with validation errors on missing fields; the date is stored as a date.
• Webhook: stores a lead against the profile in the URL, bypasses CSRF, returns 201.
• Emails: both Mailables render with the expected subject and body.

About 25 tests. They ship with the project and become the regression suite the next developer inherits.

8. Staged plan

Each stage lands as a pull request with passing tests. Production keeps running on the old runtime until stage 5.

9. Estimate and options

Excluded: changes to the separate SPA, hosting migration, new features.

Appendix. Static scan output

Produced by Rector 2 with the PHP 8.3 set and the Laravel level set up to 12, and PHPStan 2 at level 1, against a copy of the repository with its locked dependencies installed.