Warning

Laravel Breadcrumbs is no longer maintained. Please see the README for more details.

Contributing

Developing inside a real application

The easiest way to develop Laravel Breadcrumbs alongside a real Laravel application is to set it up as normal, but tell Composer to install from source with the --prefer-source flag.

If you’ve already got it installed, delete it from the vendor/ directory and re-install from source:

$ cd /path/to/repo
$ rm -rf vendor/davejamesmiller/laravel-breadcrumbs
$ composer install --prefer-source
$ cd vendor/davejamesmiller/laravel-breadcrumbs
$ git checkout -t origin/master
$ git checkout -b YOUR_BRANCH
# Make changes and commit them
$ git remote add YOUR_USERNAME git@github.com:YOUR_USERNAME/laravel-breadcrumbs
$ git push -u YOUR_USERNAME YOUR_BRANCH

There is also a test app available to simplify testing against multiple versions of Laravel.

Note

The test app is not a replacement for unit tests - we have those too - but it gives a better feel for how the package works in practice.

Using your fork in a project

If you have forked the package (e.g. to fix a bug or add a feature), you may want to use that version in your project until the changes are merged and released. To do that, simply update the composer.json in your main project as follows:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/YOUR_USERNAME/laravel-breadcrumbs.git"
        }
    ],
    "require": {
        "davejamesmiller/laravel-breadcrumbs": "dev-YOUR_BRANCH"
    }
}

Replace YOUR_USERNAME with your GitHub username and YOUR_BRANCH with the branch name (e.g. develop). This tells Composer to use your repository instead of the default one.

Unit tests

To run the unit tests, simply run:

$ cd /path/to/laravel-breadcrumbs
$ composer update
$ ./test.sh

(Note: The unit tests are not 100% complete yet, and the code will probably need some refactoring to make it easier to test.)

Code coverage

To check code coverage, you will also need Xdebug installed. Run:

$ ./test-coverage.sh

Then open test-coverage/index.html to view the results. (However, be aware of the edge cases in PHPUnit that can make it not-quite-accurate.)

Documentation

Documentation is in docs/. It is written in reStructuredText and converted to HTML and PDF formats by Sphinx.

To submit a documentation change, simply edit the appropriate file on GitHub. (There’s an “Edit on GitHub” link in the top-right corner of each page.)

Warning

Not all markup is supported by GitHub – e.g. :ref: and :doc: – so the preview may not be exactly what appears in the online documentation.

For more comprehensive documentation changes you may be better installing Sphinx so you can test the docs locally:

Installing Sphinx

You will need Python and pip to install Sphinx, the documentation generator. To install them (on Debian Wheezy or similar), you can run the following:

$ sudo apt-get install python python-pip
$ sudo pip install sphinx sphinx-autobuild sphinx_rtd_theme

To build the PDF documentation, you will also need LaTeX installed:

$ sudo apt-get install texlive texlive-latex-extra

Building documentation

To build the HTML docs (docs-html/index.html):

$ ./build-html-docs.sh

This will build the docs and run a HTML server on port 8000 that will automatically rebuild the docs and reload the page whenever you modify a file.

To build the PDF docs (docs-pdf/laravel-breadcrumbs.pdf):

$ ./build-pdf-docs.sh

Sphinx markup reference

I found the following documents useful when writing the documentation:

Heading styles

The following code styles are used for headings:

################################################################################
 Page title (80 hashes)
################################################################################

================================================================================
 Section title (80 equals signs)
================================================================================

----------------------------------------
 Heading 2 (40 hypens)
----------------------------------------

Heading 3 (full stops)
......................