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
- Create a new Laravel project alongside your existing app. In a directory next to your current application (e.g.,
/var/www/laravel-bridge), runcomposer create-project laravel/laravel bridge. This creates a fresh Laravel installation that won’t interfere with your legacy code. - Configure Laravel’s environment. Copy the
.env.exampleto.envand 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. - 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_DRIVERtodatabaseand write a small script that migrates session data. - 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', '.*');inroutes/web.php. Adjust the path to your actual legacy file. - Serve the Laravel app as the front controller. Update your web server configuration (Apache or Nginx) to point the document root to Laravel’s
publicfolder. Then, configure a rewrite rule that sends all requests to Laravel’sindex.phpexcept for static assets. This way, Laravel handles routing, and your legacy script is only invoked when needed. - 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.
- 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.
- 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.
- 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.
- 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
legacyfolder). Update your deployment scripts to runcomposer install --no-devandphp 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_DEBUGsetting 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
artisanto 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
.envfile for correct database host, port, and credentials. Test withphp artisan tinkerto run a simple query. - Performance issues. If the catch-all route is slow, consider using Laravel’s route caching. Run
php artisan route:cacheafter 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
- PowerPoint vs Keynote: Key Differences
- How to Sign Out of OneDrive in Windows 10
- Reduce Memory Use in Windows When RAM Is Low
- How to Set Up and Use Credential Manager on Windows 10
- Fix Microsoft Edge Battery Drain on Windows 11
- Type to Siri Instead of Talking on iPhone (iOS 11)