sodcalculator

10 Tech How-To

Add Laravel to a Procedural PHP App (No Rewrite)

Guide 10-58019 · Updated · Step by step

This guide shows how to introduce Laravel into an existing procedural PHP application without rewriting it from scratch. You’ll keep your current code working while gradually adding Laravel’s routing, middleware, and Eloquent ORM to new or refactored sections. This approach is ideal for legacy apps that need modern features but can’t afford a risky full rewrite.

What You’ll Need

  • An existing PHP application (procedural style) running on a server with PHP 8.1 or higher.
  • Composer installed globally or locally.
  • Access to the server’s command line (SSH or terminal).
  • Basic familiarity with Laravel’s directory structure and routing.
  • A backup of your existing application files and database.

Step-by-Step

  1. Create a new Laravel project alongside your existing app. In a directory next to your current application (e.g., /var/www/laravel-bridge), run composer create-project laravel/laravel bridge. This creates a fresh Laravel installation that won’t interfere with your legacy code.
  2. Configure Laravel’s environment. Copy the .env.example to .env and set your database credentials, queue driver, and cache settings. If your legacy app uses a different database, you can point Laravel to the same one—just ensure the credentials work.
  3. Set up a shared session and authentication bridge. To let Laravel and your legacy app share user sessions, configure Laravel’s session driver to use the same storage as your legacy app (e.g., database or Redis). If your legacy app uses PHP native sessions, you can set Laravel’s SESSION_DRIVER to database and write a small script that migrates session data.
  4. Create a legacy bootstrap file. In your Laravel project, create a route that includes your legacy application’s entry point. For example, add a route like Route::any('/{path?}', function ($path) { require base_path('legacy/index.php'); })->where('path', '.*'); in routes/web.php. Adjust the path to your actual legacy file.
  5. Serve the Laravel app as the front controller. Update your web server configuration (Apache or Nginx) to point the document root to Laravel’s public folder. Then, configure a rewrite rule that sends all requests to Laravel’s index.php except for static assets. This way, Laravel handles routing, and your legacy script is only invoked when needed.
  6. Migrate routes incrementally. Instead of moving everything at once, start by moving one simple endpoint (e.g., a contact form) to a Laravel route. Keep the legacy script for the rest. Over time, you can move more routes by creating Laravel controllers and using the legacy bootstrap only for the remaining pages.
  7. Introduce Eloquent for new data queries. For any new database operations, use Laravel’s Eloquent models. This lets you gradually replace raw SQL queries without touching existing ones. Create models that map to your existing tables.
  8. Use Laravel’s middleware for shared logic. If your legacy app has authentication or logging checks, implement them as Laravel middleware. Then, apply that middleware to the routes that need it, including the legacy catch-all route.
  9. Test thoroughly after each change. Run your existing test suite (if any) and manually check the moved endpoints. Keep a rollback plan: if a migration fails, revert the route to the legacy script.
  10. Deploy the combined app. When you’re ready, deploy the Laravel project to your production server, making sure the legacy files are accessible (e.g., inside the legacy folder). Update your deployment scripts to run composer install --no-dev and php artisan config:cache.

Common Mistakes

  • Forgetting to handle static assets. If your legacy app has CSS/JS files, make sure your web server serves them directly, not through Laravel’s router. Otherwise, you’ll get 404 errors.
  • Session conflicts. If both apps use different session drivers, users may get logged out or see inconsistent data. Ensure both use the same session storage and cookie name.
  • Path issues in legacy code. Legacy scripts often rely on relative paths or $_SERVER['SCRIPT_NAME']. When included via Laravel, these may break. Use absolute paths or adjust the script to use __DIR__.
  • Overcomplicating the bootstrap. Don’t try to make Laravel handle every legacy request at once. Start with a simple catch-all and gradually move routes.
  • Ignoring error handling. Laravel’s error handler may hide legacy errors. Configure the APP_DEBUG setting carefully and log errors from both systems.

Tips

  • Use a subdirectory for legacy files. Keep your legacy code in a separate folder (e.g., legacy/) inside the Laravel project to avoid naming conflicts.
  • Start with a non-critical page. Migrate a low-traffic page first to test the integration without risking user-facing issues.
  • Leverage Laravel’s built-in features. Use Laravel’s CSRF protection, validation, and pagination for new features—this reduces technical debt.
  • Document the migration process. Write down which routes are moved and which are still legacy. This helps your team track progress.
  • Consider using Laravel’s artisan to generate models and controllers. This speeds up the migration and keeps code consistent.

Troubleshooting

  • Legacy script not loading. Check that the path in the catch-all route is correct. Use realpath() to verify the file exists. Also ensure the web server has permission to read the file.
  • 404 errors for existing URLs. If your legacy app uses query strings or rewrite rules, Laravel’s router may not match them. Add specific routes for those patterns or adjust the catch-all to pass the full URI.
  • Session data lost. Verify that both apps use the same session driver and that the session cookie name matches. Clear your browser cookies and test again.
  • Database connection errors. Double-check the .env file for correct database host, port, and credentials. Test with php artisan tinker to run a simple query.
  • Performance issues. If the catch-all route is slow, consider using Laravel’s route caching. Run php artisan route:cache after adding routes.

Frequently Asked Questions

Will my existing PHP code still work after adding Laravel?

Yes, as long as you don’t modify the legacy files and you include them correctly via the catch-all route. The legacy code runs in the same PHP process, so it should work as before, but test thoroughly.

Can I use Laravel’s Eloquent with my existing database tables?

Absolutely. Create Eloquent models that correspond to your tables. You may need to define the table name and primary key if they don’t follow Laravel’s conventions.

How do I share authentication between the two apps?

Use the same session driver and cookie name. For example, if your legacy app uses database sessions, configure Laravel to use the same table. You can also create a custom user provider that reads from your legacy user table.

What if my legacy app uses a different PHP version?

Laravel 11 requires PHP 8.2 or higher. If your legacy app runs on an older PHP version, you may need to upgrade PHP or use an older Laravel version (e.g., Laravel 9 supports PHP 8.0). Check compatibility before proceeding.

Is it safe to deploy this combined setup to production?

Yes, if you test thoroughly and have a rollback plan. Start with a staging environment, monitor logs, and keep a backup of the original code.

Can I gradually move all routes to Laravel?

Yes, that’s the goal. As you move each route, remove it from the legacy script and add a Laravel route. Eventually, the legacy script may become empty and you can delete it.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →