LaravelPackage.com: an open course in writing Laravel packages

What the project is, and the companion example package

The LaravelPackage.com repository is the documentation source for the LaravelPackage project, and the readme describes it as a central place to learn how to create a package from scratch.

The distinguishing decision is the companion repository. All the provided examples are available as an accompanying example package named BlogPackage, which can be cloned separately, and the documentation points at it directly.

That arrangement is the reason the project is worth reading as a course rather than as reference material. A tutorial that shows you the code inline is a tutorial you follow. A tutorial that shows you the code and gives you a repository containing the same code, with the steps to make it run, is a tutorial you can fork, break and rebuild. For a subject like package development, where the point is the wiring between the service provider, the composer manifest and the configuration publishing, the ability to see a working package is most of the value.

A BlogPackage is also a good subject to teach with, because the domain is small and familiar. A package with a model, a migration, a service provider and a config file exercises every part of the Laravel package skeleton without requiring the reader to understand anything unusual about the business logic.

The licence is MIT, the project is on the master branch, and the last push to the repository was on 2026-08-09. The topic list names laravel, mkdocs, package-development and hacktoberfest, which tells you both how the site is built and that the project recruits contributors through Hacktoberfest.

Contributing with a local Python setup

Contributions are highly welcomed, and the documentation site is generated using MkDocs, so you need either a local Python setup or Docker to get started.

The local route is the standard Python one. Fork the repository and clone it locally, create a virtual environment, activate it, install the requirements and start the server:

python3 -m venv venv

source venv/bin/activate

pip install -r requirements.txt

mkdocs serve

and then open http://localhost:8000 in the browser to view the documentation site.

The virtual environment is doing the usual job of keeping the build chain out of the system Python, which matters more than usual here because the requirements file is fully pinned. The pinned set includes mkdocs at 1.4.3, mkdocs-material at 9.1.9, Markdown at 3.8.1, Pygments at 2.20.0, the pymdown-extensions at 10.16.1, Jinja2 at 3.1.6, watchdog at 3.0.0 for the live reload, and ghp-import at 2.1.0, which is the GitHub Pages import tool the deployment uses.

That last dependency is the one worth understanding, because it explains how a site like this gets published. ghp-import is the mechanism for pushing a built MkDocs site to a GitHub Pages branch in the way GitHub expects, and its presence in the requirements file means the deploy step is part of the same toolchain as the preview step. A contributor who clones the repository and runs the local server is running exactly the same Markdown and theme extensions that produce the published site, which is the point of pinning the versions.

The README gives the numbered steps as a list, with the code blocks indented under each step, which is the conventional way to write a numbered procedure in Markdown that renders on GitHub.

Contributing with Docker, and why the project offers both

The Docker route exists for contributors who would rather not install Python and MkDocs locally.

The steps are shorter. Fork the repository and clone it locally, ensure Docker is installed and running, and then from the project root run:

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

and open http://localhost:8000 in the browser to view the documentation site.

The mechanics are worth reading because they show the design. The image is the official Material for MkDocs image, and the project directory is mounted at /docs inside the container, so the container serves the site from your working copy and the server watches it, so a Markdown edit appears in the browser as you save it. The --rm flag means the container is removed when you stop it, and the --it flag keeps the container attached with a terminal so the build output is visible.

Offering both routes is the right call for an open documentation project, because the two contributors are different people. Somebody who already has Python, or who wants to edit in their own editor with their own tooling, uses the local setup. Somebody who wants to contribute a single typo and does not want to manage a virtual environment and a pinned dependency set uses the container.

The port mapping is the same in both cases, 8000, so the URL a contributor opens is the same either way, which matters for the instructions in the readme and in any issue template that tells a contributor to visit localhost:8000.

The final instruction in the readme is the one that closes the loop: when satisfied, commit your changes and submit the pull request to the master branch.

What the course is for, and why the subject is worth a whole site

The project description states the scope plainly: documentation for LaravelPackage.com, learn to create Laravel specific PHP packages from scratch, following this open documentation.

The phrase from scratch is doing the work. A package is not a library with a nice API; it is a distribution with a manifest, a service provider, a set of publishable assets, a set of routes, a config file and a set of conventions about how the host application finds all of that. Each of those is a decision that has to be made before a line of feature code is written, and each of them is a decision a package author makes once and then has to explain to every user.

That is the gap the project addresses. The questions it answers are the ones that appear in every package's GitHub issues, such as where the config file goes and how it is published, how a migration is registered so it runs on install, how the service provider is registered and when, how a package adds routes without taking over the application's routing, and how the composer manifest declares the Laravel version the package supports.

The choice to make it a single, focused course rather than a reference library of every package pattern is what makes it readable. A package developer needs one worked example that goes all the way through, and it needs to be a package that does something small enough to understand and big enough to exercise every part of the skeleton.

And putting the whole thing under an open documentation licence is the part that makes it reusable. The site is not a company tutorial that goes stale; it is a set of Markdown files in a repository, so somebody can fork it, adapt the examples to their own conventions, or translate it, and the project accepts contributions under the same MIT terms as the code it documents.

The subject also has a natural teaching shape. Package development is where a Laravel developer meets the framework's extension points for the first time, and the extension points are invisible in ordinary application code. Seeing them in the smallest possible package, with a domain model and a migration, is a good way to learn them, which is why the companion repository is not an afterthought but the other half of the course.

What the repository contains, and who is behind it

The tree is small, and it is the shape of a documentation source rather than an application.

There is a docs/ directory holding the Markdown that becomes the site, an mkdocs.yml with the site configuration, the requirements.txt we have already looked at, a .cache/ directory for the build cache, a .github/ directory for the workflows, and the .gitignore, the CODE_OF_CONDUCT.md and the LICENSE.

The mkdocs.yml is the one file worth opening, because it holds the site structure and the theme configuration, and the requirements file tells you which theme extensions are in play. The pymdown-extensions package is what provides the Markdown extensions that a documentation site like this tends to need, and the combination of a pinned theme version and a pinned extension version is what makes the rendered output reproducible.

The credits section names John Braun as the author and links to the contributors list, and the project is maintained under the MIT licence. The Hacktoberfest topic and the prominent contribution instructions point at the maintenance model, which is a documentation project that takes patches from newcomers, and the practical effect of that is that the prose is reviewed by many people and the structure is reviewed by whoever maintains the configuration.

What the repository does not contain is the example package itself, which lives in its own repository. That separation is deliberate and it is the design decision of the whole project. The documentation repository is a document, and it can be regenerated, forked or replaced without touching the code, and the code repository is a working package that can be cloned and run without reading a word of the prose.

For a project about writing packages, having the documentation and the example live in different places is a small demonstration of the separation the reader is being asked to build.

Editorial conclusion

LaravelPackage.com is worth working through if you have written Laravel applications and want to publish a package, because it covers the whole path from an empty directory to a distributable package, and because the examples are mirrored in a separate BlogPackage repository so you can read the code and the explanation side by side rather than reconstructing the code from prose. It is the wrong tool if you are looking for a package to install. Before you start, check three things: that you have the tooling the project expects, since the documentation is built with MkDocs and the Material theme, and the requirements file pins specific versions of the build chain; that you pick the setup that matches your environment, because the local Python route needs a virtual environment with the pinned requirements while the Docker route needs a working Docker daemon and mounts the project into the container; and that you know the contribution route, since the instructions are to commit your changes and submit the pull request to the master branch, and the project also runs under Hacktoberfest.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. PackagePages/LaravelPackage.com on GitHub
4. Project website
5. README