A simple symlink between the composer package and your project allows you to keep your core code all in one place.
When managing multiple Laravel projects that share common functionality, private Composer packages can be an excellent way to maintain shared code. This guide will show you how to set up and use private Composer packages efficiently in your local development workflow, particularly when working with Laravel applications.
The Challenge
I maintain two large projects that follow different development lifecycles. One serves as an “evergreen” project where features are initially developed, tested, and optimized before being rolled out to other sites. Rather than duplicating site-specific configurations, services, and core logic across each application, I centralize these in a private Composer package. This approach allows independent project management while maintaining a clean, maintainable workflow.
Local Development Setup
Directory Structure
Your local development environment might look something like this:
~/Sites/
├── app1/
│ └── vendor/
├── app2/
│ └── vendor/
└── composer-package/
└── src/
Setting Up Local Development with Symlinks
To streamline local development, we can use symlinks to connect our Composer package directly to our projects. Here’s how to set it up:
- First, run
composer install
in your project directory to ensure all dependencies are installed - Create a symlink from your package’s source to the vendor directory:
ln -s ~/Sites/composer-package/src ~/Sites/app1/vendor/vendor-name/package-name
Benefits of This Approach
This setup offers several advantages:
- Direct code sharing between projects while maintaining proper Composer versioning
- Immediate code updates without running Composer commands
- Easy branch switching for testing new features
- Maintenance of proper version control in your package code
Version Control and Branch Management
When working on new features in your Composer package:
- Create a new branch in your package repository
- Your applications will automatically use the new code through the symlink
- No need to run additional Composer commands during development
- When ready, commit your changes and create a proper release
Production Considerations
Remember that symlinks are only for local development. In production:
- Use proper versioning in your
composer.json
- Install packages normally through Composer
- Consider using private repositories or VCS repositories in your Composer configuration
Best Practices
- Always maintain proper versioning in your package
- Use semantic versioning for releases
- Document any breaking changes between versions
- Keep your package focused and maintainable
- Consider creating a development branch for major changes
This workflow significantly improves the development experience when working with private packages, especially in Laravel applications where rapid iteration and testing are common requirements.