From 53c0fb3cc5dd50f6c1c389993806607fb38f5c39 Mon Sep 17 00:00:00 2001
From: Yann B <20049273+yannoff@users.noreply.github.com>
Date: Thu, 25 Apr 2024 23:43:24 +0200
Subject: [PATCH 1/6] README: Add `Pitfalls` section

---
 README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/README.md b/README.md
index 63532ab..f2c47de 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,7 @@ PHP Code compiler - Phar executable compiling utility
 - [Install](#install)
     - [Requirements](#requirements)
     - [Quick install](#quick-install)
+- [Pitfalls](#pitfalls)
 - [License](#license)
 
 ## Usage
@@ -134,6 +135,59 @@ _Add execution permissions to the binary_
 chmod +x ${BINDIR}/phpcc
 ```
 
+## Pitfalls
+
+Here is a (non-exhaustive) list of the most common mistakes related to PHAR compiling.
+
+### Shebang line in main script
+
+Since the main (entrypoint) script will be **included** in the PHAR stub, it must not contain any shebang line, otherwise this line will be treated as text and printed to standard output when invoking the compiled PHAR.
+
+_Example: Invoking a version of `phpcc` compiled with a shebang line in `bin/compile.php`_
+
+```
+$ bin/phpcc --version
+#!/usr/bin/env php
+PHP Code Compiler version 1.3.0-dev
+```
+
+### Local versus compiled files
+
+Let's consider the following tree (all files required by the app)
+
+```
+bin/acme.php
+src/Command/Acme.php
+src/Command/SomeClass.php
+lib/Ufo.php
+```
+
+Compile it (Oops... one Unknown File Object has not been included)
+
+```
+phpcc -e bin/acme.php -f bin/acme.php -d src/ -o bin/acme
+```
+
+Guess what ?
+
+If the `bin/acme` compiled archive stays in its place, it won't fail, because `lib/Ufo.php` can still be found from its point of view.
+
+### Size too big
+
+Many projects include some dev libraries, for unit test, local data seeding or code inspection.
+
+Fact is, some of those libs have **A LOT** of dependencies... Hence the `vendor` directory, which is usually included in the archive is really **HUGE**.
+
+Q: How do we remediate then ?
+
+A: Before compiling, we ensure the `vendor` directory does not contains any dev library:
+
+```
+composer install --no-dev
+phpcc -e bin/acme.php -f bin/acme.php -d src/:php -d vendor:php -d vendor:yaml -o bin/acme
+```
+
+
 ## License
 
 Licensed under the [MIT License](LICENSE).

From bcedbaf3b3dd1006c866d18a26b67cae8b99df2e Mon Sep 17 00:00:00 2001
From: "Yann B." <20049273+yannoff@users.noreply.github.com>
Date: Mon, 20 Oct 2025 16:06:53 +0200
Subject: [PATCH 2/6] Reword pitfall

---
 README.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index f2c47de..7e5e165 100644
--- a/README.md
+++ b/README.md
@@ -168,9 +168,11 @@ Compile it (Oops... one Unknown File Object has not been included)
 phpcc -e bin/acme.php -f bin/acme.php -d src/ -o bin/acme
 ```
 
-Guess what ?
+Launching the `bin/acme` compiled archive should raise an error because of the missing file.
 
-If the `bin/acme` compiled archive stays in its place, it won't fail, because `lib/Ufo.php` can still be found from its point of view.
+Well...not. What happens here then ?
+
+If the `bin/acme` compiled archive stays in its place,the `lib/Ufo.php` can still be found from its point of view.
 
 ### Size too big
 
@@ -178,9 +180,9 @@ Many projects include some dev libraries, for unit test, local data seeding or c
 
 Fact is, some of those libs have **A LOT** of dependencies... Hence the `vendor` directory, which is usually included in the archive is really **HUGE**.
 
-Q: How do we remediate then ?
+Q: How to remediate then ?
 
-A: Before compiling, we ensure the `vendor` directory does not contains any dev library:
+A: Before compiling, ensure the `vendor` directory does not contains any dev library:
 
 ```
 composer install --no-dev

From 27f2d95953fe1500a4682f858c1705c5e6c433e7 Mon Sep 17 00:00:00 2001
From: "Yann B." <20049273+yannoff@users.noreply.github.com>
Date: Thu, 30 Oct 2025 19:21:29 +0100
Subject: [PATCH 3/6] Update local vs compiled files

---
 README.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/README.md b/README.md
index 7e5e165..19d8732 100644
--- a/README.md
+++ b/README.md
@@ -153,6 +153,8 @@ PHP Code Compiler version 1.3.0-dev
 
 ### Local versus compiled files
 
+#### Trap 1: file missing in compiled phar but present in local working dir
+
 Let's consider the following tree (all files required by the app)
 
 ```
@@ -174,6 +176,16 @@ Well...not. What happens here then ?
 
 If the `bin/acme` compiled archive stays in its place,the `lib/Ufo.php` can still be found from its point of view.
 
+#### Trap 2: different files with the same relative path
+
+Eg: 
+
+```php
+require "vendor/autoload.php"
+```
+
+TODO: explain, give workaround
+
 ### Size too big
 
 Many projects include some dev libraries, for unit test, local data seeding or code inspection.

From 39919a64cd3165abade03d8578ce499f22b0a68a Mon Sep 17 00:00:00 2001
From: "Yann B." <20049273+yannoff@users.noreply.github.com>
Date: Thu, 30 Oct 2025 19:25:13 +0100
Subject: [PATCH 4/6] Update pitfalls links in TOC

---
 README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/README.md b/README.md
index 19d8732..8d87b29 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,9 @@ PHP Code compiler - Phar executable compiling utility
     - [Requirements](#requirements)
     - [Quick install](#quick-install)
 - [Pitfalls](#pitfalls)
+    - [Shebang line in main script](#shebang-line-in-main-script)
+    - [Local versus compiled files](#local-versus-compiled-files)
+    - [Size too big](#size-too-big)
 - [License](#license)
 
 ## Usage

From 338a2bae5940219398c9a578e6728d4e6e0aef78 Mon Sep 17 00:00:00 2001
From: Yannoff <yannoff.it@gmail.com>
Date: Thu, 30 Oct 2025 20:44:12 +0100
Subject: [PATCH 5/6] Update pitfall trap 2

---
 README.md | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 8d87b29..5bd5994 100644
--- a/README.md
+++ b/README.md
@@ -173,12 +173,19 @@ Compile it (Oops... one Unknown File Object has not been included)
 phpcc -e bin/acme.php -f bin/acme.php -d src/ -o bin/acme
 ```
 
+##### Problem
+
 Launching the `bin/acme` compiled archive should raise an error because of the missing file.
 
 Well...not. What happens here then ?
 
 If the `bin/acme` compiled archive stays in its place,the `lib/Ufo.php` can still be found from its point of view.
 
+##### Solution
+
+Always move the compiled executable **out** of the project's working directory before testing it.
+
+
 #### Trap 2: different files with the same relative path
 
 Eg: 
@@ -187,7 +194,29 @@ Eg:
 require "vendor/autoload.php"
 ```
 
-TODO: explain, give workaround
+Chances are, there might be such a `vendor/autoload.php` file in the project to be compiled.
+
+##### Problem
+
+From the compiled app point of view, `vendor/autoload.php` refers to a relative path in the PHAR archive.
+
+##### Workaround
+
+The phpcc execution dir (i.e the compiled project's top directory) must be added first in the include path.
+
+For example in the main entrypoint script:
+
+```php
+// bin/main.php
+
+// ensure we load the execution directory's autoload, not the
+// one included in the compiled phar executable
+set_include_path(getcwd() . PATH_SEPARATOR . get_include_path());
+
+require 'vendor/autoload.php';
+
+// ...
+```
 
 ### Size too big
 

From c2d8e4e8411fc05e58790e3613106e9c03cc0d86 Mon Sep 17 00:00:00 2001
From: "Yann B." <20049273+yannoff@users.noreply.github.com>
Date: Fri, 31 Oct 2025 11:22:43 +0100
Subject: [PATCH 6/6] Rework pitfall tree

---
 README.md | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 5bd5994..8ce3996 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,8 @@ PHP Code compiler - Phar executable compiling utility
     - [Quick install](#quick-install)
 - [Pitfalls](#pitfalls)
     - [Shebang line in main script](#shebang-line-in-main-script)
-    - [Local versus compiled files](#local-versus-compiled-files)
+    - [Local versus compiled files: missing file](#local-versus-compiled-files-missing-file)
+    - [Local versus compiled files: name collision](#local-versus-compiled-files-name-collision)
     - [Size too big](#size-too-big)
 - [License](#license)
 
@@ -154,9 +155,7 @@ $ bin/phpcc --version
 PHP Code Compiler version 1.3.0-dev
 ```
 
-### Local versus compiled files
-
-#### Trap 1: file missing in compiled phar but present in local working dir
+### Local versus compiled files: missing file
 
 Let's consider the following tree (all files required by the app)
 
@@ -173,7 +172,7 @@ Compile it (Oops... one Unknown File Object has not been included)
 phpcc -e bin/acme.php -f bin/acme.php -d src/ -o bin/acme
 ```
 
-##### Problem
+#### Problem
 
 Launching the `bin/acme` compiled archive should raise an error because of the missing file.
 
@@ -181,12 +180,12 @@ Well...not. What happens here then ?
 
 If the `bin/acme` compiled archive stays in its place,the `lib/Ufo.php` can still be found from its point of view.
 
-##### Solution
+#### Solution
 
 Always move the compiled executable **out** of the project's working directory before testing it.
 
 
-#### Trap 2: different files with the same relative path
+### Local versus compiled files: name collision
 
 Eg: 
 
@@ -196,11 +195,11 @@ require "vendor/autoload.php"
 
 Chances are, there might be such a `vendor/autoload.php` file in the project to be compiled.
 
-##### Problem
+#### Problem
 
 From the compiled app point of view, `vendor/autoload.php` refers to a relative path in the PHAR archive.
 
-##### Workaround
+#### Workaround
 
 The phpcc execution dir (i.e the compiled project's top directory) must be added first in the include path.