Local workflow for private Composer packages in Laravel

A simple symlink between the composer package and your project allows you to keep your core code all in one place.

Categories: Development

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:

  1. First, run composer install in your project directory to ensure all dependencies are installed
  2. 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:

  1. Create a new branch in your package repository
  2. Your applications will automatically use the new code through the symlink
  3. No need to run additional Composer commands during development
  4. 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.


Adam Patterson

Adam Patterson

User Interface Designer & Developer with a background in UX. I have spent 5 years as a professionally certified bicycle mechanic and ride year-round.

I am a husband and father of two, I enjoy photography, music, movies, coffee, and good food.

You can find me on Twitter, Instagram, and YouTube!