Skip to content

docs: Update README installation and usage details #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pixelated-au merged 1 commit into from
Feb 12, 2026
Merged

docs: Update README installation and usage details #9

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 36 additions & 39 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,21 @@
# Streamline: Self-update your Laravel deployment

[//]: # ([![Latest Version on Packagist](https://img.shields.io/packagist/v/pixelated-au/streamline.svg?style=flat-square)](https://packagist.org/packages/pixelated-au/streamline))

[//]: # ([![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/pixelated-au/streamline/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/pixelated-au/streamline/actions?query=workflow%3Arun-tests+branch%3Amain))

[//]: # ([![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/pixelated-au/streamline/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/pixelated-au/streamline/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain))

[//]: # ([![Total Downloads](https://img.shields.io/packagist/dt/pixelated-au/streamline.svg?style=flat-square)](https://packagist.org/packages/pixelated-au/streamline))
[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/pixelated-au/streamline/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/pixelated-au/streamline/actions?query=workflow%3Arun-tests+branch%3Amain)
[![Total Downloads](https://img.shields.io/packagist/dt/pixelated-au/streamline.svg?style=flat-square)](https://packagist.org/packages/pixelated-au/streamline)

This specialised tool is designed to help you self-update your Laravel deployment directly from GitHub.

_Unlike other tools, this project assumes your package includes all built assets and composer vendor packages._
_This project assumes your package includes all built front-end JavaScript assets._

Using artisan, you can update the package via the CLI or a tool such as Laravel Envoy.

## Installation

You can install the package via composer:
During beta, you can install the package via composer:

```bash
composer require pixelated-au/streamline
composer require pixelated-au/streamline:dev-main
```

You can publish the config file with:
Expand All @@ -28,6 +24,15 @@ You can publish the config file with:
php artisan vendor:publish --tag="streamline-config"
```

You will need to set the following environment variables in your `.env` file.
- Replace [github] and [project-name] with your GitHub repository.
- Version installed is the version of the package that is currently installed. It will be set automatically.

```dotenv
STREAMLINE_GITHUB_RELEASE_REPOSITORY=[github]/[project-name]
STREAMLINE_APPLICATION_VERSION_INSTALLED=v0.0.0
```

## Events

This library emits two events for hooking into updates:
Expand All @@ -46,55 +51,47 @@ There are several Artisan commands that you can interact with:
- `streamline:list` Retrieves the available updates from GitHub and stores them in the cache
- `streamline:run-update` CLI update of the software. Make sure to back up first!

## Common Questions
## Questions

What is the point of this project?
: Unlike other updater projects available (which are excellent by the way), this runs an update by calling an external
PHP script/class. For performance reasons, Laravel loads classes dynamically. If updating directly within Laravel, the
application may fail to load classes that have been removed/deprecated causing the update to fail, leaving a broken
site. This project runs an update by calling an external PHP script/class, ensuring that during the update, there is an
extremely low chance of the update failing.

Why is does this project assume all front-end assets will be pre-compiled?
: To bypass any potential compilation needs. Building a release of a project using something like CI or doing it locally
ensures that when it's deployed, there are no post-processing requirements. For example, you don't need to have NPM or
Node installed. You don't need to worry about the version of Node that's installed either. It simplifies updates

Does this need Composer installed? OR How do I run Composer to install dependencies?
: Whilst technically you can utilise Composer after an update, this package doesn't support it. The reasoning being the
same as the previous answer on front-end-assets. When we don't depend on Composer as part of the installation process,
we won't get build errors during an upgrade.
: Yes, Composer is required to install dependencies. It happens automatically as part of the update.

Who is this for?
: First up, it's not for all projects! It was built so that a project could be deployed on single-instance machines, not
unlike upgrading a WordPress instance. It's designed to simplify deployment - moving the build/dependency mechanics into
a centralised place such as CI. For example, this could be used inside a cPanel hosting environment.
: It was built so that a project could be deployed on single-instance machines, not unlike upgrading a WordPress
instance. It's designed to simplify deployment - moving the build/dependency mechanics into a centralised place such as
CI. For example, this could be used inside a cPanel hosting environment.

Who's it not for?
: If you have a project being deployed onto virtual machines inside of dedicated environments, other 'updater' projects
: If you have a project being deployed onto virtual machines inside dedicated environments, other 'updater' projects
may suit your needs more than this project. That said, this project was designed with extensibility in mind. As such, if
you're keen to extend it, you can eiter do a pull request or extend it locally in your project.
you're keen to extend it, you can either do a pull request or extend it locally in your project.

What other whizzbang features does this have?
: Unlike other updater projects available (which are excellent by the way), this runs an update by calling an external
PHP script/class. This ensures that during the update, the only classes loaded into memory are directly attached to this
project.
Extending/Customising
: Streamline is built upon a pipeline architecture, so you can inject your own steps into the update process. For
example, if you wish to make it build your front-end assets instead of using pre-built assets, you can create a new
pipeline step.

: Use the config file `config/streamline.php` to customise the update process to suit your needs.

: As part of its optimisation techniques, Laravel (and potentially child libraries) doesn't load all classes into
memory. This is great except when after an update, Laravel may try to load said classes. Again, not a problem...
except if those classes have been removed/deprecated! If that happens, the deployment will halt/fail and will require
manual work. Not good if you want a self-maintainable product!
: You can also create your own implementation of `Pixelated\Streamline\Interfaces\UpdateBuilderInterface` which is the
tool to progressively gather information about the update process before the final update is run.

## Changelog

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

## Contributing

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

## Security Vulnerabilities

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

## Credits

- [Pixelated](https://github.com/pixelated-au)
- [All Contributors](../../contributors)

## TODO
- [ ] Detect if the GitHub token has expired. If so, output an error to the user

Expand Down