Setting up Laravel packages locally to contribute to open-source

Published on September 4th, 2020.

Recently, I've started to contribute to a few open-source codebases, like the Statamic one.

Initially I only really contributed small changes like fixing typos on the docs and adjusting v-if somewhere. When I was doing that I would just fork the Statamic repo on Github, make the change on the Github online editor and make a pull request. Simple! (obviously I checked the change worked locally before hand)

However, when I wanted to do a change that was a little bigger where I needed to make changes to a bunch of different files. I thought it was probably about time to set everything up properly.

There's loads of ways you can set stuff up when you're wanting to develop Laravel packages, but I've chosen what seems to me as the easiest solution.

Symlinks....

Symlinks are basically little links/shortcuts on your system. You can set them up so you can point a file or directory to another file or directory somewhere else on your system. They can come in useful in a lot of cases, including this one.

Let me give you a brief rundown of my workflow when working with Laravel packages locally:

First, I have a fork of the open-source repository I'm working on. For example, with Statamic I have a Github fork at damcclean/cms and it's cloned inside my ~/Sites/cms directory.

When I cloned my fork to my computer, I also setup an additional remote for the real Statamic repo.

git remote add statamic [email protected]:statamic/cms.git

The additional fork allows me to pull down the latest changes from the official Statamic Github repository without doing a merge or pull request to sync them.

If I just merged them, it would do some funny stuff with my Git history and it could cause problems later on when creating a pull request.

git checkout master
git pull statamic master

Now that we've sorted the fork, let's talk about how to set it up with an actual Statamic project so you can try out your changes in an actual site.

You'll need to have an existing Statamic site on your machine, it doesn't matter what starter kit it's using or if it was originally a Laravel app, all that matters is that it uses Statamic.

Whenever you want to swap out the version of Statamic you've got from Packagist to the fork you've got sitting on your machine, you can use a little alias which will create the required symlink.

Before you actually use it though, you'll need to add something to your bash profile or your zsh aliases file. If you've never heard of either of those things before, hopefully this blog post might be helpful to you.

Anyways back to it.... add this to your bash profile or your zsh aliases file. You can change plslink to whatever you want. You might also want to adjust the public dist directory and the vendor directory to match up with the package you're working with.

plslink() {
  if [ "$1" = 'dist' ] || [ "$1" = 'cp' ]; then
    rm -rf public/vendor/statamic/cp
    ln -s ~/Sites/cms/resources/dist public/vendor/statamic/cp
  elif [ -n "$1" ]; then
    rm -rf vendor/statamic/$1
    ln -s ~/Sites/$1 vendor/statamic/$1
  fi

  echo "\nIn vendor/statamic:"
  la vendor/statamic
  echo "\nIn public/vendor/statamic:"
  la public/vendor/statamic
}

After you've done that, you'll want to open a new Terminal tab and navigate to the site you want to pop your local fork in.

Now all that's left to do is to run our alias command. We're going to run it twice so that we link up both the public assets and the vendor files to where they're supposed to live. This should do it:

  • plslink cms

  • plslink dist

My picture

Duncan McClean