From eaabdc14ba21c7cc31c88665065a39073c1541c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Th=C3=A9o=20FIDRY?= Date: Mon, 27 Nov 2023 07:06:59 +0100 Subject: [PATCH] fix --- doc/code-isolation.md | 8 ++++---- doc/configuration.md | 28 +++++++++++++--------------- doc/docker.md | 8 ++++---- doc/phar-signing.md | 7 +++---- doc/requirement-checker.md | 8 ++++---- doc/symfony.md | 2 +- 6 files changed, 29 insertions(+), 32 deletions(-) diff --git a/doc/code-isolation.md b/doc/code-isolation.md index bb07a4d24..652979d1d 100644 --- a/doc/code-isolation.md +++ b/doc/code-isolation.md @@ -7,7 +7,7 @@ ## Why/Explanation -When bundling the code in a PHAR, it is equivalent to compacting all the code in a single file. However unlike in a +When bundling the code in a PHAR, it is equivalent to compacting all the code in a single file. However unlike in a compiled language, the code does not change. This, when the PHAR _loads_ external code, can lead to dependency conflicts. @@ -22,7 +22,7 @@ myapp.phar myscript.php For the sake of the example, `myapp.phar` is using Composer and loads the YAML component right away when starting, i.e. when running `myapp.phar`, the class `Symfony\Yaml\Yaml` _from the PHAR_ is going to be loaded. Now what `myapp.phar` is actually going to do is scan the whole file given, and do some reflection work on each classes found. I.e. for each -class `$class` found, it will do `new \ReflectionClass($class)`. +class `$class` found, it will do `new \ReflectionClass($class)`. Now if `myscript.php` is using the Symfony YAML 4.0.0 component with some new features added in 4.0.0 that are non-existent in 2.8.0, when doing `new \ReflectionClass('Symfony\Yaml\Yaml')`, the class `Symfony\Yaml\Yaml` will be @@ -45,12 +45,12 @@ Box provides an integration with [PHP-Scoper][php-scoper]. To use it, [enable th compactor][php-scoper-compactor]. If you need an extra configuration for PHP-Scoper, you can create a `scoper.inc.php` file as -[per the documentation][php-scoper-config]. The only difference is that you can ignore the `finders` setting as the +[per the documentation][php-scoper-config]. The only difference is that you can ignore the `finders` setting as the files to scope are already collected by Box. And that's it! -Warning: keep in mind however that scoping is a very brittle process due to the nature of PHP. As such you will likely +Warning: keep in mind however that scoping is a very brittle process due to the nature of PHP. As such you will likely need some adjustments in your code or the configuration. diff --git a/doc/configuration.md b/doc/configuration.md index 4cab5c2ce..1ca46d14c 100644 --- a/doc/configuration.md +++ b/doc/configuration.md @@ -128,7 +128,7 @@ When the parameter is not given or set to `null`, Box tries to guess the binary `composer.json` file. If the [Composer `bin`][composer-bin] is set, Box will pick the first value provided. Otherwise it will fallback on the [PHAR][phar class] default file used which is `index.php`. -The main file contents is processed by the [compactors][compactors] as the other files. +The main file contents is processed by the [compactors][compactors] as the other files. If the main file starts with a shebang line (`#!`), it will be automatically removed (the shebang line goes in the [stub][stub] for a PHAR and is configured by the [shebang][shebang] setting). @@ -158,9 +158,9 @@ constraint before running. See more information about it [here][requirement-chec the requirement checker will be added. Note that this is true only if either the `composer.json` or `composer.lock` could have been found. -!!! Warning +!!! Warning this check is still done within the PHAR. As a result, if [the required extension to open the PHAR][compression] - due to the compression algorithm is not loaded, a hard failure will still appear: the requirement + due to the compression algorithm is not loaded, a hard failure will still appear: the requirement checker _cannot_ be executed before that. @@ -196,7 +196,7 @@ The `force-autodiscovery` (`bool` default `false`) setting forces Box to attempt though you are using the [`directories`][directories] or [`finder`][finder] setting. When Box tries to find which files to include, it may remove some files such as readmes or test files. If however you -are using the [`directories`][directories] or [`finder`][finder], Box will _append_ the found files to the ones you +are using the [`directories`][directories] or [`finder`][finder], Box will _append_ the found files to the ones you listed. @@ -228,7 +228,7 @@ Files listed in the [`blacklist`][blacklist] will not be added to the PHAR. the files such as images, those that contain binary data or simply a file you do not want to alter at all despite using compactors. -!!! Warning +!!! Warning Setting the key `directories` (regardless of its value), will disable the file auto-discovery. If you want to keep it, check the [force the auto-discovery][force-autodiscovery] setting. @@ -243,7 +243,7 @@ compactors. included in `directories` (respectively `directories-bin`), the those files **will be included**. The files included are a union of the directives. -!!! Warning +!!! Warning Symlinks are not followed/supported. @@ -252,7 +252,7 @@ compactors. The finder (`object[]`|`null` default `[]`) setting is a list of JSON objects. Each object (key, value) tuple is a (method, arguments) of the [Symfony Finder][symfony-finder] used by Box. If an array of values is provided for a single key, the method will be called once per value in the array. - + Note that the paths specified for the `in` method are relative to [`base-path`][base-path] and that the finder will account for the files registered in the [`blacklist`][blacklist]. @@ -379,8 +379,8 @@ The `vendor` directory will have `beberlei/assert` and `bamarni/composer-bin-plu disabled, the `bamarni/composer-bin-plugin` package will be removed from the PHAR. This setting will automatically be disabled when [`dump-autoload`][dump-autoload] is disabled. Indeed, otherwise some -files will not be shipped in the PHAR but may still appear in the Composer autoload classmap, resulting in an -autoloading error. +files will not be shipped in the PHAR but may still appear in the Composer autoload classmap, resulting in an +autoloading error. ### Map (`map`) @@ -421,7 +421,7 @@ the above files will be stored with the following paths in the PHAR: The [PHAR stub][phar.fileformat.stub] file is the PHAR bootstrapping file, i.e. the very first file executed whenever the PHAR is executed. It usually contains things like the PHAR configuration and executing the [main script file][main]. -The default PHAR stub file can be used but Box also propose a couple of options to customize the stub used. +The default PHAR stub file can be used but Box also propose a couple of options to customize the stub used. ### Stub (`stub`) @@ -661,7 +661,7 @@ command ✨. ### Annotations (`annotations`) The annotations (`boolean`|`object`|`null` default `true`) setting is used to enable compacting annotations in PHP source -code. +code. This setting is only taken into consideration if the [`KevinGH\Box\Compactor\Php` compactor][compactors] is enabled. @@ -790,7 +790,7 @@ available: By default, PHARs are `SHA1` signed. -The `OPENSSL` algorithm will require to provide [a key][key]. +The `OPENSSL` algorithm will require to provide [a key][key]. !!! warning @@ -850,7 +850,7 @@ With the configuration excerpt: Then the `Phar::getMetadata()` will return `['application_version' => '1.0.0-dev']` array. -!!! warning +!!! warning Your callable function must be readable by your autoloader. @@ -1071,9 +1071,7 @@ The short commit hash will only be used if no tag is available. [security]: #security [shebang]: #shebang-shebang [timestamp]: #forcing-the-timestamp-timestamp -[the signing best practices]: ./phar-signing.md#phar-signing-best-practices [stub-stub]: #stub-stub [stub]: #stub [symfony-finder]: https://symfony.com/doc/current//components/finder.html [zlib-extension]: https://secure.php.net/manual/en/book.zlib.php -[#1152]: https://github.com/box-project/box/issues/1152 diff --git a/doc/docker.md b/doc/docker.md index 4c8de6005..e13c39444 100644 --- a/doc/docker.md +++ b/doc/docker.md @@ -3,19 +3,19 @@ Besides generating a PHAR, you may want to create a [Docker][docker] image for your application. To do so, you can either: -- Directly generate the `Dockerfile` when generating the PHAR with the `--with-docker` option of the Box `compile` +- Directly generate the `Dockerfile` when generating the PHAR with the `--with-docker` option of the Box `compile` command - Generate the `Dockerfile` for a given PHAR with the Box `docker` command -The command will attempt to generate a `Dockerfile` for your PHAR, leveraging the -[requirement checker][requirement-checker]. Once the file generated, you have free hands on it: you can either use it +The command will attempt to generate a `Dockerfile` for your PHAR, leveraging the +[requirement checker][requirement-checker]. Once the file generated, you have free hands on it: you can either use it right away (you just need to run `$ docker build .` to create the docker image) or you can tweak it however you want. In your `Dockerfile` (generated by Box), you should see the following line: ```Dockerfile RUN $(php -r '$extensionInstalled = array_map("strtolower", \get_loaded_extensions(false));$requiredExtensions = ["zlib", "phar", "openssl", "pcre", "tokenizer"];$extensionsToInstall = array_diff($requiredExtensions, $extensionInstalled);if ([] !== $extensionsToInstall) {echo \sprintf("docker-php-ext-install %s", implode(" ", $extensionsToInstall));}echo "echo \"No extensions\"";') -``` +``` This cryptic one-liner PHP script is about installing the required extensions for your application: it compares the ones your application requires with the ones already provided by the base PHP image, and then install them using the diff --git a/doc/phar-signing.md b/doc/phar-signing.md index 32bad5309..3930ea1e1 100644 --- a/doc/phar-signing.md +++ b/doc/phar-signing.md @@ -145,7 +145,7 @@ gpg --keyserver keys.openpgp.org --send-key 96C8013A3CC293C465EE3FBB03B2F4DF7A20 ``` [^1]: - + There is several OpenPGP Keyservers. It is recommended to push your keys to [keys.openpgp.org] _at least_, but you can also push it to other servers if you wish to. @@ -156,7 +156,7 @@ revocation certificate to the keyserver to invalidate the signing key. gpg --output revoke-96C8013A3CC293C465EE3FBB03B2F4DF7A20DF08.asc --gen-revoke 96C8013A3CC293C465EE3FBB03B2F4DF7A20DF08 ``` -This will leave you with a revocation certificate in the file `revoke-96C8013A3CC293C465EE3FBB03B2F4DF7A20DF08.asc` +This will leave you with a revocation certificate in the file `revoke-96C8013A3CC293C465EE3FBB03B2F4DF7A20DF08.asc` which can be added to your password manager. @@ -194,7 +194,7 @@ ideally one generated and managed by a password manager. This leaves you with a file `keys.asc.gpg`. You can add this one to the repository and at this point you are probably better off **deleting the `keys.asc` file**. In order to do the actual signing, you will have to decrypt it again, but -it is better to not keep that decrypted key around. +it is better to not keep that decrypted key around. ### Sign your PHAR @@ -390,5 +390,4 @@ Credits: [keys.openpgp.org]: https://keys.openpgp.org/about [github-environment-secrets]: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions [github-workflow]: https://docs.github.com/en/actions/using-workflows -[phive]: https://phar.io/ [jar]: https://docs.oracle.com/javase/8/docs/technotes/guides/jar/jarGuide.html diff --git a/doc/requirement-checker.md b/doc/requirement-checker.md index 1e8445f55..e385d1b57 100644 --- a/doc/requirement-checker.md +++ b/doc/requirement-checker.md @@ -23,14 +23,14 @@ requirements are passing on the right in debug verbosity. !!! Warning this check is still done within the PHAR. As a result, if [the required extension to open the PHAR][compression] - due to the compression algorithm is not loaded, a hard failure will still appear: + due to the compression algorithm is not loaded, a hard failure will still appear: the requirement checker _cannot_ be executed before that. ## Configuration Box will retrieve all the (non-dev) requirements including the ones of the dependencies if there is any. When a -`composer.lock` file is present, it will take the information from it. If not found, it will fallback on the +`composer.lock` file is present, it will take the information from it. If not found, it will fallback on the `composer.json` but that it will not be able to retrieve any information regarding the dependencies requirements in this case. @@ -126,8 +126,8 @@ PHP 7.2.5+ compatible, it will fail before the requirements are being checked. ## Skipping the requirement checker -When the requirement checker is shipped, you can always skip it by setting the environment variable -`BOX_REQUIREMENT_CHECKER` to `0`. For example if you are using the `box.phar` which ships a requirement checker and want +When the requirement checker is shipped, you can always skip it by setting the environment variable +`BOX_REQUIREMENT_CHECKER` to `0`. For example if you are using the `box.phar` which ships a requirement checker and want to skip it, you can run: ```shell diff --git a/doc/symfony.md b/doc/symfony.md index 883db9772..f99d7caee 100644 --- a/doc/symfony.md +++ b/doc/symfony.md @@ -24,7 +24,7 @@ doc. ## Project directory -Symfony 5.1+ defines the "project dir" as the directory where the composer.json file is. Because box deletes it during PHAR compilation, you need to redefine it in your Kernel. It is usually located in `src/Kernel.php` and can be defined as follow: +Symfony 5.1+ defines the "project dir" as the directory where the composer.json file is. Because box deletes it during PHAR compilation, you need to redefine it in your Kernel. It is usually located in `src/Kernel.php` and can be defined as follow: ```php