BookStack Code Mirror - website/blob - content/blog/2025/php-dependency-improvements.md

   1 +++
   2 categories = ["News"]
   3 tags = ["News"]
   4 title = "Testing Better Dependency Management"
   5 image = "/images/blog-cover-images/cc-by-sa-4/mountain-stream-agnes-monkelbaan.jpg"
   6 author = "Dan Brown"
   7 slug = "php-dependency-improvements"
   8 draft = false
   9 date = 2025-03-17T18:00:00Z
  10 +++
  11
  12 Yesterday I released [BookStack v25.02.1](https://github.com/BookStackApp/BookStack/releases/tag/v25.02.1)
  13 which included a range of updates to [the system CLI](https://www.bookstackapp.com/docs/admin/system-cli/),
  14 one of which being a new command:
  15
  16 ```bash
  17 ./bookstack-system-cli download-vendor
  18 ```
  19
  20 This new command will download the required PHP dependency packages for a BookStack instance,
  21 and is intended to replace the existing `composer install --no-dev` install & update
  22 step with a more efficient system which relies on fewer external sources.
  23
  24 The existing `composer install --no-dev` command will continue to work, and will remain the default advised
  25 approach until this new option has had greater testing.
  26
  27 *Note: If you don't run our standard install steps (For example, you run via a maintained docker image) then this
  28 is not something you'd use yourself or need to worry about.*
  29
  30 ### How This Works
  31
  32 As part of the BookStack release process the `vendor/` folder, which contains PHP dependencies,
  33 is now compressed to a ZIP archive and then uploaded to our https://files.bookstackapp.com/vendor/
  34 site, with the resulting ZIP file name matching the BookStack version.
  35 A sha256 checksum is saved as part of the core code-base to a [`dev/checksums/vendor` file](https://github.com/BookStackApp/BookStack/blob/release/dev/checksums/vendor), which is committed as part of a release.
  36
  37 When running `./bookstack-system-cli download-vendor`, the CLI will look up to our https://files.bookstackapp.com/vendor/
  38 site for the ZIP of version matching the BookStack instance, download that ZIP, then verify the file against
  39 the checksum stored in the code-base. If this passes, the ZIP is extracted to `vendor/` in the target BookStack
  40 instance, removing any existing `vendor/` directory first.
  41
  42 The process has been designed to be fairly simple, in a way that can easily be replicated via other means
  43 outside of our CLI, while also ensuring a level of trust & security by performing the checksum
  44 against a value provided via a different source to the downloaded file.
  45
  46 ### Why This Has Been Introduced
  47
  48 There's a few reasons as to why this process has been implemented:
  49
  50 Firstly, it reduces requirements for a production environment.
  51 Right now [composer](https://getcomposer.org/) is considered a BookStack requirement,
  52 but this process can be used instead of composer in standard production use.
  53
  54 Secondly, it can be a lot more efficient than the existing `composer install --no-dev` step.
  55 That existing method will download & extract multiple ZIP files, one for each dependency to install/update.
  56 This new command/process packages up all dependencies for a BookStack version within a single ZIP to download & extract.
  57
  58 Thirdly, it reduces reliance on external services & platforms.
  59 The existing process via composer will download files from GitHub (Microsoft) and Codeberg (and any other repository sources that might be used in future).
  60 This new process only relies on a single host that's under the BookStack domain: https://files.bookstackapp.com.
  61 This can be particularly helpful in environments where connections to external locations are strictly controlled, and also helps avoid issues that can occur with downloading from third-party sites like rate-limiting and access filtering.
  62 This also works towards our wider goal of [reducing our reliance on GitHub](https://github.com/BookStackApp/BookStack/issues/4551) within the project.
  63
  64 ### Providing Feedback
  65
  66 I welcome any feedback regarding this system [on the GitHub issue here](https://github.com/BookStackApp/BookStack/issues/5538).
  67
  68 Once we've had some feedback, and the system is proven stable & working, I'll look to update our docs, guidance and scripts
  69 to use this new system by default instead of using composer.
  70
  71 ---
  72
  73 <span style="font-size: 0.8em;opacity:0.8;">Header Image Credits: &nbsp;<span>Photo by <a href="https://commons.wikimedia.org/wiki/File:S-charl_richting_Alp_Sesvenna._12-10-2024._(actm.)_03.jpg">Agnes Monkelbaan (CC-BY-SA-4)</a> - Image Modified</span></span>