BUPH-87 | Encapsulate Symfony Expression Language

README.md

@@ -32,7 +32,7 @@ Buphalo leverages an environment variable API for runtime options. The following
 Neighborhoods_Buphalo_V1_TargetApplication_BuilderInterface__SourceDirectoryPath=/PATH/TO/SOURCE/DIRECTORY \
 Neighborhoods_Buphalo_V1_TargetApplication_BuilderInterface__FabricationDirectoryPath=/PATH/TO/FABRICATION/DIRECTORY \
 Neighborhoods_Buphalo_V1_TargetApplication_BuilderInterface__NamespacePrefix=VENDOR\\PRODUCT\\ \
-Neighborhoods_Buphalo_V1_TemplateTree_Map_Builder_FactoryInterface__TemplateTreeDirectoryPaths=/PATH/TO/TEMPLATE/TREE/DIRECTORY \
+Neighborhoods_Buphalo_V1_TemplateTree_Map_Builder_FactoryInterface__TemplateTreeDirectoryPaths=TreeName:/PATH/TO/TEMPLATE/TREE/DIRECTORY \
 php bin/v1/buphalo
 ```
 
@@ -41,7 +41,7 @@ For example, in order to Buphalo Buphalo (assuming Buphalo is installed as a com
 Neighborhoods_Buphalo_V1_TargetApplication_BuilderInterface__SourceDirectoryPath=$PWD/vendor/neighborhoods/buphalo/src/v1 \
 Neighborhoods_Buphalo_V1_TargetApplication_BuilderInterface__FabricationDirectoryPath=$PWD/vendor/neighborhoods/buphalo/fab/v1 \
 Neighborhoods_Buphalo_V1_TargetApplication_BuilderInterface__NamespacePrefix=Neighborhoods\\Buphalo\\ \
-Neighborhoods_Buphalo_V1_TemplateTree_Map_Builder_FactoryInterface__TemplateTreeDirectoryPaths=$PWD/vendor/neighborhoods/buphalo/template-tree/V1 \
+Neighborhoods_Buphalo_V1_TemplateTree_Map_Builder_FactoryInterface__TemplateTreeDirectoryPaths=buphalo:$PWD/vendor/neighborhoods/buphalo/template-tree/V1 \
 php vendor/bin/v1/buphalo
 ```
 
@@ -55,7 +55,7 @@ environment variable. As an env var this is "typed" as a CSV. It is then cast to
 Neighborhoods_Buphalo_V1_TargetApplication_BuilderInterface__SourceDirectoryPath=$PWD/vendor/neighborhoods/buphalo/src/v1 \
 Neighborhoods_Buphalo_V1_TargetApplication_BuilderInterface__FabricationDirectoryPath=$PWD/vendor/neighborhoods/buphalo/fab/v1 \
 Neighborhoods_Buphalo_V1_TargetApplication_BuilderInterface__NamespacePrefix=Neighborhoods\\Buphalo\\ \
-Neighborhoods_Buphalo_V1_TemplateTree_Map_Builder_FactoryInterface__TemplateTreeDirectoryPaths=$PWD/vendor/neighborhoods/buphalo/template-tree/V1 \
+Neighborhoods_Buphalo_V1_TemplateTree_Map_Builder_FactoryInterface__TemplateTreeDirectoryPaths=buphalo:$PWD/vendor/neighborhoods/buphalo/template-tree/V1 \
 Neighborhoods_Buphalo_V1_FabricationFile_Map_BuilderInterface__FinderFileNames=Connection.buphalo.v1.fabrication.yml,Connection2.buphalo.v1.fabrication.yml 
 php vendor/bin/v1/buphalo
 ```
@@ -189,11 +189,23 @@ actors:
 ### Adding A New Or Updating An Existing Template
 * Copy Buphalo's `template-tree` directory to your software product's root directory if you have not done so already.
 * Add or change the appropriate PHP and dependency injection service definition YAML files in the position that you want them under your `template-tree/v1` directory.
-* Be sure to update your environmental varaible to the following (or the equivalent if you used a different path for the copied directory)
+* Be sure to update your environmental variable to the following (or the equivalent if you used a different path for the copied directory)
 ```bash
-Neighborhoods_Buphalo_V1_TemplateTree_Map_Builder_FactoryInterface__TemplateTreeDirectoryPaths=/PATH/TO/SOFTWARE_PRODUCT/ROOT/template-tree/v1 \
+Neighborhoods_Buphalo_V1_TemplateTree_Map_Builder_FactoryInterface__TemplateTreeDirectoryPaths=TreeName:/PATH/TO/SOFTWARE_PRODUCT/ROOT/template-tree/v1 \
 ```
 
+### Using Multiple Template Trees
+* Buphalo supports using multiple template trees.
+* If using multiple trees, each template tree MUST be named by including a "TreeName:" prefix to the directory path
+* If using a single template tree, the template tree identifier MAY be left unnamed.
+* Separate each path identifier with a comma
+* Buphalo will attempt to look through the template tree directories in the order specified, and will use the first matching template it finds
+* example:
+```
+Neighborhoods_Buphalo_V1_TemplateTree_Map_Builder_FactoryInterface__TemplateTreeDirectoryPaths=primary:/PATH/TO/SOFTWARE_PRODUCT/ROOT/template-tree/primary,secondary:/PATH/TO/SOFTWARE_PRODUCT/ROOT/template-tree/secondary \
+```
+
+
 ## Definitions
 
 ### Fabrication File

bin/v1/buphalo

@@ -3,4 +3,4 @@
 declare(strict_types=1);
 error_reporting(E_ALL);
 
-include_once __DIR__ . 'buphalo.php';
+include_once __DIR__ . '/buphalo.php';

bin/v1/generate-symfony-expression-language.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+cd "$(dirname "$0")" || exit
+cd ../..
+Neighborhoods_Buphalo_V1_TargetApplication_BuilderInterface__SourceDirectoryPath=$PWD/src \
+Neighborhoods_Buphalo_V1_TargetApplication_BuilderInterface__FabricationDirectoryPath=$PWD/fab \
+Neighborhoods_Buphalo_V1_TargetApplication_BuilderInterface__NamespacePrefix=Neighborhoods\\Buphalo\\ \
+Neighborhoods_Buphalo_V1_TemplateTree_Map_Builder_FactoryInterface__TemplateTreeDirectoryPaths=$PWD/template-tree/V1 \
+Neighborhoods_Buphalo_V1_FabricationFile_Map_BuilderInterface__FinderFileNames=\
+ExpressionLanguageDecorator.buphalo.v1.fabrication.yml,\
+ExpressionLanguage.buphalo.v1.fabrication.yml \
+php bin/v1/buphalo

bin/v1/makephar

@@ -3,4 +3,4 @@
 declare(strict_types=1);
 error_reporting(E_ALL);
 
-include_once __DIR__ . 'makephar.php';
+include_once __DIR__ . '/makephar.php';

bin/v1/upgrade

@@ -3,4 +3,4 @@
 declare(strict_types=1);
 error_reporting(E_ALL);
 
-include_once __DIR__ . 'upgrade.php';
+include_once __DIR__ . '/upgrade.php';

docker/xdebug.ini

@@ -9,5 +9,5 @@ xdebug.remote_enable=On
 xdebug.remote_autostart=On
 xdebug.remote_connect_back=Off
 xdebug.remote_mode=req
-xdebug.remote_port=9001
-xdebug.remote_host=docker.for.mac.localhost
+xdebug.remote_port=9040
+xdebug.remote_host=dockerhost

docs/Upgrading.md

@@ -12,7 +12,7 @@ This should allow you to upgrade specific files as desired in case there are iss
     As such, we recommend maintaining your own template directory where it'll be easier to include your own templates
     as you find the need for them.
 
-- Do a search/replace to change all occurences of `Neighborhoods\Bradfab` in your new template directory to
+- Do a search/replace to change all occurences of `Neighborhoods\Bradfab\Template` in your new template directory to
   `Neighborhoods\BuphaloTemplateTree`
 - Replace all `Actor` references with `PrimaryActorName`, including moving files/directories.
 
@@ -27,7 +27,7 @@ This should allow you to upgrade specific files as desired in case there are iss
       probably ended in `Template/Actor/` (because Bradfab did not support Primary Actor Generation).
       Because Buphalo *does* support Primary Actor Generation, you should probably remove `Actor/` from this variable.
   - If you are using both Bradfab and Buphalo during a transition period:
-    - Use the bradfab `1.0.0-eol` release which has fixes to prevent it from reading Buphalo files.
+    - Use the bradfab `1.0.0-beta9` release which has fixes to prevent it from reading Buphalo files.
     - Have your `buphalo.sh` script target a different directory than bradfab does and then merge the two directories
       with something like `cp -R`.
 
@@ -36,4 +36,4 @@ If you find that the automatic upgrade script isn't sufficient and you need to k
 let us know.
 In the interim, you can delete any `.buphalo.v1.fabrication.yml` files that aren't working for you and stick with your
 old bradfab files until you can get everything working in Buphalo.
-(As above, you will need to upgrade bradfab to `1.0.0-eol`.)
+(As above, you will need to upgrade bradfab to `1.0.0-beta9`.)

src/V1/Actor/Template/Builder.php

@@ -7,13 +7,15 @@
 use Neighborhoods\Buphalo\V1\Actor\TemplateInterface;
 use Neighborhoods\Buphalo\V1\FabricationFile;
 use Neighborhoods\Buphalo\V1\TemplateTree;
+use Neighborhoods\Buphalo\V1\TemplateTreeInterface;
 use RuntimeException;
 
 class Builder implements BuilderInterface
 {
     use Factory\AwareTrait;
     use Actor\AwareTrait;
     use FabricationFile\Actor\AwareTrait;
+    use FabricationFile\AwareTrait;
     use TemplateTree\Map\Repository\AwareTrait;
 
     protected $FilePath;
@@ -32,20 +34,77 @@ public function build(): TemplateInterface
     protected function getFilePath(): string
     {
         if ($this->FilePath === null) {
-            $actorTemplateFilePathCandidate = sprintf(
-                '%s/%s',
-                $this->getTemplateTreeMapRepository()->get()->current()->getDirectoryPath(),
-                $this->getFabricationFileActor()->getTemplateRelativeFilePath()
-            );
-            $actorTemplateFilePath = realpath($actorTemplateFilePathCandidate);
-            if ($actorTemplateFilePath === false) {
-                throw new RuntimeException(
-                    sprintf('The actor template file [%s] does not exist.', $actorTemplateFilePathCandidate)
-                );
+            $actorTemplateFilePathCandidates = $this->buildActorTemplateFilePathCandidates();
+            foreach($actorTemplateFilePathCandidates as $actorTemplateFilePathCandidate) {
+                $actorTemplateFilePath = realpath($actorTemplateFilePathCandidate);
+                if ($actorTemplateFilePath !== false) {
+                    $this->FilePath = $actorTemplateFilePath;
+                    return $this->FilePath;
+                }
             }
-            $this->FilePath = $actorTemplateFilePath;
+
+            throw new RuntimeException(
+                sprintf('No actor template file was found, checked: %s', implode(',', $actorTemplateFilePathCandidates))
+            );
         }
 
         return $this->FilePath;
     }
+
+    private function buildActorTemplateFilePathCandidates(): array
+    {
+        $actorTemplateFilePathCandidates = [];
+
+        $templateTreeMap = $this->getTemplateTreeMapRepository()->get();
+
+        // Let the Actor preferences be used over the Fabrication File ones
+        if ($this->getFabricationFileActor()->hasPreferredTemplateTrees()) {
+            foreach($this->getFabricationFileActor()->getPreferredTemplateTrees() as $treeName) {
+                if (isset($templateTreeMap[$treeName])) {
+                    $path = $this->buildTemplatePath($templateTreeMap[$treeName]);
+                    $actorTemplateFilePathCandidates[$path] = true;
+                } else {
+                    throw new \RuntimeException(
+                        sprintf('Template tree %s referenced in %s > %s has not been defined.',
+                            $treeName,
+                            $this->getFabricationFile()->getFilePath(),
+                            $this->getFabricationFileActor()->getFileName()
+                        )
+                    );
+                }
+            }
+        }
+
+        // Let the Fabrication File preferences be used over global ones
+        if ($this->getFabricationFile()->hasPreferredTemplateTrees()) {
+            foreach ($this->getFabricationFile()->getPreferredTemplateTrees() as $treeName) {
+                if (isset($templateTreeMap[$treeName])) {
+                    $path = $this->buildTemplatePath($templateTreeMap[$treeName]);
+                    $actorTemplateFilePathCandidates[$path] = true;
+                } else {
+                    throw new \RuntimeException(
+                        sprintf('Template tree %s referenced in %s has not been defined.',
+                            $treeName,
+                            $this->getFabricationFile()->getFilePath()
+                        )
+                    );
+                }
+            }
+        }
+
+        foreach($templateTreeMap as $templateTree) {
+            $path = $this->buildTemplatePath($templateTree);
+            $actorTemplateFilePathCandidates[$path] = true;
+        }
+
+        return array_keys($actorTemplateFilePathCandidates);
+    }
+
+    private function buildTemplatePath(TemplateTreeInterface $templateTree): string
+    {
+        return implode(DIRECTORY_SEPARATOR, [
+            $templateTree->getDirectoryPath(),
+            $this->getFabricationFileActor()->getTemplateRelativeFilePath(),
+        ]);
+    }
 }

src/V1/Actor/Template/BuilderInterface.php

@@ -6,6 +6,7 @@
 use Neighborhoods\Buphalo\V1\Actor\TemplateInterface;
 use Neighborhoods\Buphalo\V1\ActorInterface;
 use Neighborhoods\Buphalo\V1\FabricationFile;
+use Neighborhoods\Buphalo\V1\FabricationFileInterface;
 
 interface BuilderInterface
 {
@@ -14,4 +15,6 @@ public function build(): TemplateInterface;
     public function setActor(ActorInterface $Actor);
 
     public function setFabricationFileActor(FabricationFile\ActorInterface $FabricationFileActor);
+
+    public function setFabricationFile(FabricationFileInterface $FabricationFileActor);
 }

src/V1/Actor/Template/Tokenizer/Builder.php

@@ -21,6 +21,7 @@ public function build(): TokenizerInterface
         $templateBuilder = $this->getActorTemplateBuilderFactory()->create();
         $templateBuilder->setActor($this->getActor());
         $templateBuilder->setFabricationFileActor($this->getFabricationFileActor());
+        $templateBuilder->setFabricationFile($this->getFabricationFile());
         $actorTemplate = $templateBuilder->build();
 
         $annotationTokenizerBuilder = $this->getActorTemplateAnnotationTokenizerBuilderFactory()->create();

src/V1/Buphalo.php

@@ -3,6 +3,8 @@
 
 namespace Neighborhoods\Buphalo\V1;
 
+use InvalidArgumentException;
+use LogicException;
 use Neighborhoods\Buphalo\V1\Fabricator\FactoryInterface;
 use Neighborhoods\Buphalo\V1\Protean;
 use ReflectionClass;
@@ -11,21 +13,67 @@ class Buphalo implements BuphaloInterface
 {
     use Protean\Container\Builder\AwareTrait;
 
+    protected const CAN_CACHE_CONTAINER = 'Neighborhoods_Buphalo_V1_Buphalo__CanCacheContainer';
+
+    private $CanCacheContainerFromEnvironment;
+    private $CanCacheContainer;
+
     public function run(): BuphaloInterface
     {
+        /** @noinspection PhpUnhandledExceptionInspection */
         $this->getProteanContainerBuilder()->setCachedContainerFileName(
             sprintf(
                 '%s.php',
                 (new ReflectionClass($this))->getShortName()
             )
         );
         $this->getProteanContainerBuilder()->setCanBuildZendExpressive(false);
-        $this->getProteanContainerBuilder()->setCanCacheContainer(false);
+        $this->getProteanContainerBuilder()->setCanCacheContainer($this->getCanCacheContainer());
         $this->getProteanContainerBuilder()->registerServiceAsPublic(FactoryInterface::class);
         /** @var FabricatorInterface $fabricator */
         $fabricator = $this->getProteanContainerBuilder()->build()->get(FactoryInterface::class)->create();
         $fabricator->fabricate();
 
         return $this;
     }
+
+    public function getCanCacheContainer(): bool
+    {
+        if ($this->CanCacheContainer === null) {
+            $this->CanCacheContainer = $this->getCanCacheContainerFromEnvironment();
+        }
+
+        return $this->CanCacheContainer;
+    }
+
+    public function setCanCacheContainer(bool $CanCacheContainer): BuphaloInterface
+    {
+        if ($this->CanCacheContainer !== null) {
+            throw new LogicException('Can Cache Container is already set.');
+        }
+
+        $this->CanCacheContainer = $CanCacheContainer;
+
+        return $this;
+    }
+
+    protected function getCanCacheContainerFromEnvironment(): bool
+    {
+        if (isset($_ENV[self::CAN_CACHE_CONTAINER])) {
+            if ($_ENV[self::CAN_CACHE_CONTAINER] === 'true' || $_ENV[self::CAN_CACHE_CONTAINER] === 'false') {
+                $this->CanCacheContainerFromEnvironment = (bool)$_ENV[self::CAN_CACHE_CONTAINER];
+            } else {
+                throw new InvalidArgumentException(
+                    sprintf('%s is not boolean. Given "%s"',
+                        self::CAN_CACHE_CONTAINER,
+                        $_ENV[self::CAN_CACHE_CONTAINER]
+                    )
+                );
+            }
+        } else {
+            $this->CanCacheContainerFromEnvironment = false;
+        }
+
+        return $this->CanCacheContainerFromEnvironment;
+    }
 }

src/V1/FabricationFile.php

@@ -15,6 +15,7 @@ class FabricationFile implements FabricationFileInterface
     protected $RelativeDirectoryPath;
     protected $DirectoryPath;
     protected $Actors;
+    protected $PreferredTemplateTrees;
 
     public function getActors(): Actor\MapInterface
     {
@@ -155,4 +156,29 @@ public function setDirectoryPath(string $DirectoryPath): FabricationFileInterfac
 
         return $this;
     }
+
+    public function getPreferredTemplateTrees(): array
+    {
+        if ($this->PreferredTemplateTrees === null) {
+            throw new \LogicException('FabricationFile PreferredTemplateTrees has not been set.');
+        }
+
+        return $this->PreferredTemplateTrees;
+    }
+
+    public function hasPreferredTemplateTrees(): bool
+    {
+        return $this->PreferredTemplateTrees !== null;
+    }
+
+    public function setPreferredTemplateTrees(string ...$PreferredTemplateTrees): FabricationFileInterface
+    {
+        if ($this->PreferredTemplateTrees !== null) {
+            throw new \LogicException('FabricationFile PreferredTemplateTrees is already set.');
+        }
+
+        $this->PreferredTemplateTrees = $PreferredTemplateTrees;
+
+        return $this;
+    }
 }