From 72f56b66fce824a33ba46f0a714f2748fbb920b6 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] README: Add `Pitfalls` section

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

diff --git a/README.md b/README.md
index 04383ea..5b86b48 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
@@ -132,6 +133,47 @@ _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.
+
+### 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).