Merge pull request #16 from phonetworks/new_outgoing_edges

New outgoing edges

CHANGELOG.md

@@ -0,0 +1,18 @@
+# CHANGELOG
+
+This changelog references the relevant changes (bug and security fixes) introduced with version 8.0 and beyond.
+
+To get the diff for a specific change, go to https://github.com/phonetworks/pho-framework/commit/XXX where XXX is the change hash.
+
+To get the diff between two versions, go to https://github.com/phonetworks/pho-framework/compare/v8.0.0...v7.5.0
+
+## 7.5 to 8.0
+
+* With particles, the ```registerOutgoingEdgeClass``` is gone, and is now replaced with ```registerOutgoingEdge```.
+* The {ParticleName}/{EdgeName}Out folder structure to define edges is now replaced with the explicit "registerOutgoingEdge" method only.
+* Particle's ```registerHandlerAdapter(string $class)``` method is replaced with ```registerHandler(string $class)```.
+* Two new signals; outgoing_edge.registered and edge.registered
+* ParticleTrait __construct (which was imported by particles via "particleConstructor" name) is now named as: "initializeParticle".
+* The internals of OutgoingEdgeLoader simplified.
+* Documentation (under docs/) updated to reflect the latest API changes.
+* Unit tests updated to reflect the latest changes in the API.

VERSION

@@ -1 +1 @@
-7.5.0
+8.0.0

docs/02-Architecture.md

@@ -22,7 +22,9 @@ the edge, its predicate, and notification, all in separate files. Alternatively,
 
 To reiterate, the predicate and notification classes are optional.
 
-> There is an alternative way of adding outgoig edge classes to the particles. You can do so by using the particle's
-> ```registerOutgoingEdgeClass(string $edge_class_name, int $trim = 2)``` method if the edge class is already included. 
-> Although  please note, the predicate and notification classes, if they are available, must be renamed in conformance to 
-> afore-mentioned requirements, and must reside in the same namespace with the edge class.
+Once you define an edge class (with the recommended directory structure above) you must register it via:
+
+```registerOutgoingEdge(...string $class)```
+
+Although  please note, the predicate and notification classes, if they are available, must be renamed in conformance to 
+afore-mentioned requirements, and must reside in the same namespace with the edge class.

docs/05-Particles.md

@@ -1,12 +1,10 @@
 # Particles
 
-The function below defines the edges that this particle accepts:
+Edges must be defined at object construction via 
+* ```registerIncomingEdges(...string $class)``` 
+* and ```registerOutgoingEdges(...string $class)```
 
-```php
-$this->registerIncomingEdges(ActorOut\Write::class);
-```
-
-This must be called in the constructor, before calling the parent particle's constructor. Any edge that claims that this particle is its tail, and that has not been already registered by the particle's parent, must be defined here, otherwise an exception will be thrown.
+Any edge that claims that this particle is its tail, and that has not been already registered by the particle's parent, must be defined, otherwise an exception will be thrown when trying to access edge methods.
 
 Secondly, you can define field constraints and directives for particles by setting up a **FIELDS** constant in the particle head.
 

docs/07-Handlers.md

@@ -10,7 +10,7 @@ Handlers are virtual methods in use by particles. Virtual methods are created to
 These adapters can be replaced, or more can be added using handler adapters via ```registerHandlerAdapter(string $handler_key, string $handler_class)``` function. For example:
 
 ```php
-$this->registerHandlerAdapter(
+$this->registerHandler(
             "form",
             \Pho\Kernel\Foundation\Handlers\Form::class);
 ```

docs/08-Signals.md

@@ -1,5 +1,9 @@
 # Signals
 
-* **notification.received**: called when the actor received a notification. This may alternatively be achieved by overriding the ```observeNotificationListUpdate(AbstractNotification $notification)``` function.
+* **notification.received(AbstractNotification $notification)**: called when the actor received a notification. This may alternatively be achieved by overriding the ```observeNotificationListUpdate(AbstractNotification $notification)``` function.
 
-* **incoming_edge.registered**: called by particles when registering incoming edges. This function may be used extra edges easily and independently, without extending the constructor itself.
+* **incoming_edge.registered(string $class)**: called by particles when registering incoming edges. This function may be used extra edges easily and independently, without extending the constructor itself.
+
+* **outgoing_edge.registered(string $class)**: called by particles when registering outgoing edges. This function may be used extra edges easily and independently, without extending the constructor itself.
+
+* **edge.registered(string $direction, string $class)**: called by particles when registering edges. This function may be used extra edges easily and independently, without extending the constructor itself.

src/Pho/Framework/Actor.php

@@ -26,9 +26,7 @@
 class Actor extends \Pho\Lib\Graph\Node implements ParticleInterface, \SplObserver, \SplSubject
 {
 
-    use ParticleTrait {
-        ParticleTrait::__construct as particleConstructor;
-    }
+    use ParticleTrait;
 
     /**
      * Current context that this actor is in.
@@ -51,7 +49,11 @@ public function __construct(ContextInterface $context)
         $this->creator_id = (string) $this->id();
         $this->notifications = new NotificationList($this);
         $this->enter($context);
-        $this->particleConstructor();
+        $this->addEdges("outgoing",
+            ActorOut\Read::class, 
+            ActorOut\Subscribe::class, 
+            ActorOut\Write::class
+        )->initializeParticle();
     }
 
     /**

src/Pho/Framework/Cargo/AbstractEdgeCargo.php

@@ -49,4 +49,14 @@ abstract class AbstractEdgeCargo implements CargoInterface
      */
     public $singularLabel_class_pairs = [];
 
+    /**
+     * Constructor
+     *
+     * @param array $edges
+     */
+    public function __construct(array $edges = []) 
+    {
+        $this->classes = $edges;
+    }
+
 }

src/Pho/Framework/Cargo/IncomingEdgeCargo.php

@@ -56,7 +56,7 @@ class IncomingEdgeCargo extends AbstractEdgeCargo
      * A simple array of tail labels of incoming edges in singular.
      * Tail labels in string format.
      *
-     * @var array An array of labels in string format.
+     * {@inheritDoc}
      */
     public $singularLabels = [];
 
@@ -67,17 +67,8 @@ class IncomingEdgeCargo extends AbstractEdgeCargo
      * and associated class name as value.
      * Both in string format.
      *
-     * @var array An array of labels as key, and class names as value.
+     * {@inheritDoc}
      */
     public $singularLabel_class_pairs = [];
 
-    /**
-     * Constrcutor
-     *
-     * @param array $incoming_edges
-     */
-    public function __construct(array $incoming_edges = []) 
-    {
-        $this->classes = $incoming_edges;
-    }
 }

src/Pho/Framework/Graph.php

@@ -30,17 +30,16 @@
 class Graph extends \Pho\Lib\Graph\SubGraph implements ParticleInterface, ContextInterface, \SplObserver, \SplSubject
 {
 
-    use ParticleTrait  {
-        ParticleTrait::__construct as particleConstructor;
-    }
+    use ParticleTrait;
 
     public function __construct(Actor $creator, ContextInterface $context) 
     {
         parent::__construct($context);
         $this->creator = $creator;
         $this->creator_id = (string) $creator->id();
-        $this->registerIncomingEdges(ActorOut\Write::class);
-        $this->particleConstructor();
+        $this
+            ->addEdges("incoming", ActorOut\Write::class)
+            ->initializeParticle();
     }
 
      /**

src/Pho/Framework/Handlers/Gateway.php

@@ -84,7 +84,7 @@ public function __construct(ParticleInterface $particle) {
      * 
      * @return void
      */
-    public function registerHandlerAdapter(string $key, string $class): void
+    public function register(string $key, string $class): void
     {
         $this->adapters[$key] = $class;
     }

src/Pho/Framework/Loaders/OutgoingEdgeLoader.php

@@ -34,76 +34,15 @@ class OutgoingEdgeLoader extends AbstractLoader
      */
     public static function pack(Framework\ParticleInterface $particle): AbstractLoader
     {
-        $obj = new OutgoingEdgeLoader;
-        // !!! we use reflection method so that __DIR__ behaves properly with child classes.
-        $self_reflector = new \ReflectionObject($particle);
-        if($self_reflector->isAnonymous()) {
-            return $obj;
-        }
-
-        $edge_dir = 
-            dirname($self_reflector->getFileName()) . 
-            DIRECTORY_SEPARATOR . 
-            $self_reflector->getShortName() 
-            . "Out";  
-        // !!! do not replace this with __DIR__
-
-        if(!file_exists($edge_dir)) {
-            Framework\Logger::warning("Edge directory %s does not exist", $edge_dir);
-            return $obj;
-        }
-
-        $locator = new \Zend\File\ClassFileLocator($edge_dir);
-        foreach ($locator as $file) {
-            $filename = str_replace($edge_dir . DIRECTORY_SEPARATOR, '', $file->getRealPath());
-            foreach ($file->getClasses() as $class) {
-                self::registerOutgoingEdgeClass($particle, $obj->cargo, $class);
-            }
-        }
-        return $obj;
-    }
-
-    /**
-     * Calculates how many arguments in constructor to skip
-     *
-     * Used with formative predicates.
-     * The default value is 2 for framework, 3 for microkernel.
-     * 
-     * @param Framework\ParticleInterface $particle
-     * 
-     * @return int
-     */
-    protected static function getFormativeTrim(Framework\ParticleInterface $particle): int
-    {
-        $trim = 2;
-        if(defined(get_class($particle)."::FORMATIVE_TRIM_CUT"))
-            $trim = $particle::FORMATIVE_TRIM_CUT;
-        return $trim;
-    }
-
-    /**
-     * Registers an Edge Out class that meets the requirements.
-     *
-     * @param OutgoingEdgeCargo $cargo The cago to fill data with
-     * @param string $class
-     * @param int $formative_trim how many arguments in constructor to skip
-     * 
-     * @return void
-     */
-    public static function registerOutgoingEdgeClass(
-        ParticleInterface $particle,
-        OutgoingEdgeCargo & $cargo, 
-        string $class
-        ): void
-    {   
-                $reflector = new \ReflectionClass($class);
+        $obj = new OutgoingEdgeLoader($particle->getRegisteredOutgoingEdges());
+        foreach ($obj->cargo->classes as $class) {
+            $cargo = &$obj->cargo;
+            $reflector = new \ReflectionClass($class);
                 if(!$reflector->isSubclassOf(Framework\AbstractEdge::class)) { 
-                    return;
+                    continue;
                 }
-
                 $_method = (string) strtolower($reflector->getShortName());
                 $_predicate = $class."Predicate";
-
                 if($_predicate::T_FORMATIVE) {
                     $cargo->formative_labels[] = $_method;
                     $cargo->formative_label_class_pairs[$_method] = $class;
@@ -165,12 +104,32 @@ public static function registerOutgoingEdgeClass(
                         $cargo->setter_label_settable_pairs[$_method] = 
                             $reflector->getConstant("SETTABLES") ;
                 }
-
                 $_method = $reflector->getConstant("HEAD_LABELS");
                 $cargo->labels[] = $_method;
                 $cargo->label_class_pairs[$_method] = $class;
                 $_method = $reflector->getConstant("HEAD_LABEL");
                 $cargo->singularLabels[] = $_method;
                 $cargo->singularLabel_class_pairs[$_method] = $class;
+        }
+        return $obj;
+    }
+
+    /**
+     * Calculates how many arguments in constructor to skip
+     *
+     * Used with formative predicates.
+     * The default value is 2 for framework, 3 for microkernel.
+     * 
+     * @param Framework\ParticleInterface $particle
+     * 
+     * @return int
+     */
+    protected static function getFormativeTrim(Framework\ParticleInterface $particle): int
+    {
+        $trim = 2;
+        if(defined(get_class($particle)."::FORMATIVE_TRIM_CUT"))
+            $trim = $particle::FORMATIVE_TRIM_CUT;
+        return $trim;
     }
+
 }

src/Pho/Framework/Object.php

@@ -24,17 +24,17 @@
 class Object extends \Pho\Lib\Graph\Node implements ParticleInterface, \SplObserver, \SplSubject
 {
 
-    use ParticleTrait {
-        ParticleTrait::__construct as particleConstructor;
-    }
+    use ParticleTrait;
 
     public function __construct(Actor $creator, ContextInterface $context) 
     {
         parent::__construct($context);
         $this->creator = $creator;
         $this->creator_id = (string) $creator->id();
-        $this->registerIncomingEdges(ActorOut\Write::class);
-        $this->particleConstructor();
+        $this
+            ->addEdges("incoming", ActorOut\Write::class)
+            ->addEdges("outgoing", ObjectOut\Mention::class)
+            ->initializeParticle();
     }
 
 }