README

Makes an unpacked version of the vagrant environment generated by puphpet.com available via composer and Packagist.

This repo represents a snapshot of the PuPHPet project. It includes minimal tooling designed to fetch a copy of the PuPHPet release ZIP file and import it back into this project. This project includes a composer.json file, making it possible to include puphpet in another target project using composer.

There are a still a number of things that could stand to improve. For those, see:

⚠️ Big Important Warning ⚠️

This package uses a composer custom installer that does very non-standard, typically bad, things, including overwriting files in your project outside of the vendor/ directory.

This is something that composer very explicitly says we should not be doing. We break this very good and wise rule only because the tools we're working with (vagrant and puphpet) leave us with no other practical choice.

❗ Using this package will cause any root level /Vagrantfile and /puphpet/ folder in your existing project to be unceremoniously overwritten without notice, and a /.gitignore to be created or modified. Do not complain about this. This is what this package is designed to do and you've been duly warned of its danger.

Requirements

composer
vagrant
A project of your own in which you'd like to use PuPHPet via composer.

Installation

Run the following command to include the vagrant environment provided by PuPHPet in your project:

$ composer require --dev "phpfu/puphpet:@stable"

Usage

Once you've included the package as instructed above, you should be able to run vagrant with the default configuration immediately:

vagrant up

Customizing

To customize the vagrant box, you have two choices:

Copy the default /puphpet/config.yaml file provided to /puphpet.yaml and edit it to suit your needs. When an existing /puphpet.yaml file is found in your project, it will be copied to /puphpet/config.yaml for this package to use.

You can generate an appropriate config.yaml file using the puphpet.com web interface. Once you download the resulting puphpet.zip file, take just the puphpet/config.yaml file and save it into your project as puphpet.yaml.

In either case, your puphpet.yaml file should be committed to your own project's source control system so the vagrant virtual machine remains identical for all developers on the project.

@TODO: What about files/ and exec-* scripts?

Running the release scraper

This project includes a shell script designed to fetch the latest puphpet.zip file from puphpet.com, unpack it, and commit it back into this repo.

git clone git@github.com:loadsys/puphpet-release.git
cd puphpet-release
bin/scrape-release.sh

This script is intended be scheduled to run via cron to update the repo periodically. It must be run from a clone of the remote repo that Packagist is aware of and that has ssh permission to push back to the remote repository.

Packagist expects semantic versioning, and this presents a challenge. The puphpet.com project does not conform to semver and the project makes backwards-incompatible changes frequently. To work around this, the release script automatically tags each new version using a minor number. This allows consuming projects to target a specific point release that will never auto-update in a breaking way.

The consequence is that consuming projects must manually update their targeted version and verify it is still operational for their needs (as well as check that their puphpet.yaml file is up to date.)

Contributing

See the Contributing section of the loadsys/puphpet-release-composer-installer package for instructions on working with these two projects.

License

MIT. In particular, all PuPHPet work belongs to the original authors. This project is strictly for our own convenience.

phpfu / puphpet

Maintainers

Details