Generics in PHP via PHPDocs

If you did not know that you can use Generics in PHP or you do not exactly know how to use it or why you should use it, then the next examples are for you.

Type variables via @template

The @template tag allows classes and functions to declare a generic type parameter. The next examples starts with simple functions, so that we understand how it works, and then we will see the power of this in classes.


A dummy function that will return the input.

https://phpstan.org/r/1922279b-9786-4523-939d-dddcfd4ebb86

    <?php    

    /**
     * @param \Exception $param
     * @return \Exception
     *
     * @template T of \Exception
     * @psalm-param T $param
     * @psalm-return T
     */
    function foo($param) { ... }

    foo(new \InvalidArgumentException()); // The static-analysis-tool knows that 
                                          // the type is still "\InvalidArgumentException" 
                                          // because of the type variable.

@template T of \Exception // here we create a new type variable, and we force that it must be an instance of \Exception

@phpstan-param T $param // here we say that the static-analysis-tool need to remember the type that this variable had before (you can use @psalm-* or @phpstan-* both works with both tools)

@phpstan-return T // and that the return type is the same as the input type 


A simple function that gets the first element of an array or a fallback. 

In the @param PHPDocs we write “mixed” because this function can handle different types. But this information is not very helpful if you want to understand programmatically what the code does, so we need to give the static-analysis-tools some more information. 

https://phpstan.org/r/1900a2af-f5c1-4942-939c-409928a5ac4a

    <?php
     
    /**
     * @param array<mixed> $array
     * @param mixed        $fallback <p>This fallback will be used, if the array is empty.</p>
     *
     * @return mixed|null
     *
     * @template TFirst
     * @template TFirstFallback
     * @psalm-param TFirst[] $array
     * @psalm-param TFirstFallback $fallback
     * @psalm-return TFirst|TFirstFallback
     */
    function array_first(array $array, $fallback)
    {
        $key_first = array_key_first($array);
        if ($key_first === null) {
            return $fallback;
        }

        return $array[$key_first];
    }

    array_first([1, 2, 3], null); 

    if ($a === 'foo') { // The static-analysis-tool knows that 
                        // === between int|null and 'foo' will always evaluate to false.
	    // ...
    }

@template TFirst // we again define your typed variables

@template TFirstFallback // and one more because we have two inputs where we want to keep track of the types

@psalm-param TFirst[] $array // here we define that $array is an array of TFirst types

@psalm-param TFirstFallback $fallback // and that $fallback is some other type that comes into this function

@psalm-return TFirst|TFirstFallback // now we define the return type as an element of  the $array or the $fallback type 


 Very basic Active Record + Generics

The IDE support for generics is currently not there, :-/ so that we still need some hacks (see @method) for e.g. PhpStorm to have autocompletion.

https://phpstan.org/r/f88f5cd4-1bb9-4a09-baae-069fddb10b12

https://github.com/voku/phpstorm_issue_53352/tree/master/src/Framework/ActiveRecord

<?php

class ActiveRow
{
    /**
     * @var ManagedFactory<static>
     */
    public $factory;

    /**
     * @param Factory<ActiveRow>|ManagedFactory<static> $factory
     * @param null|array                                $row
     */
    public function __construct(Factory $factory, array $row = null) {
        $this->factory = &$factory;
    }
}

/**
 * @template T
 */
abstract class Factory
{
    /**
     * @var string
     *
     * @internal
     *
     * @psalm-var class-string<T>
     */
    protected $classname;

    /**
     * @return static
     */
    public static function create() {
        return new static();
    }
}

/**
 * @template  T
 * @extends   Factory<T>
 */
class ManagedFactory extends Factory
{
    /**
     * @param string $classname
     *
     * @return void
     *
     * @psalm-param class-string<T> $classname
     */
    protected function setClass(string $classname): void
    {
        if (\class_exists($classname) === false) {
            /** @noinspection ThrowRawExceptionInspection */
            throw new Exception('TODO');
        }

        if (\is_subclass_of($classname, ActiveRow::class) === false) {
            /** @noinspection ThrowRawExceptionInspection */
            throw new Exception('TODO');
        }

        $this->classname = $classname;
    }

    // ...
}

final class Foo extends ActiveRow {

    public int $foo_id;

    public int $user_id;

    // --------------------------------------
    // add more logic here ...
    // --------------------------------------
}

/**
 * @method Foo[] fetchAll(...)
 *
 * @see Foo
 *
 * // warning -> do not edit this comment by hand, it's auto-generated and the @method phpdocs are for IDE support       
 * //         -> https://gist.github.com/voku/3aba12eb898dfa209a787c398a331f9c
 *
 * @extends ManagedFactory<Foo>
 */
final class FooFactory extends ManagedFactory
{
    // -----------------------------------------------
    // add sql stuff here ...
    // -----------------------------------------------
}

A more complex collection example.

In the end we can extend the “AbstractCollection” and the static-analysis-tools knows the types of all the methods. 

https://github.com/voku/Arrayy/tree/master/src/Type

/**
 * @template TKey of array-key
 * @template T
 * @template-extends \ArrayObject<TKey,T>
 * @template-implements \IteratorAggregate<TKey,T>
 * @template-implements \ArrayAccess<TKey|null,T>
 */
class Arrayy extends \ArrayObject implements \IteratorAggregate, \ArrayAccess, \Serializable, \JsonSerializable, \Countable
{ ... }

/**
 * @template TKey of array-key
 * @template T
 * @template-extends \IteratorAggregate<TKey,T>
 * @template-extends \ArrayAccess<TKey|null,T>
 */
interface CollectionInterface extends \IteratorAggregate, \ArrayAccess, \Serializable, \JsonSerializable, \Countable
{ ... }

/**
 * @template   TKey of array-key
 * @template   T
 * @extends    Arrayy<TKey,T>
 * @implements CollectionInterface<TKey,T>
 */
abstract class AbstractCollection extends Arrayy implements CollectionInterface
{ ... }

/**
 * @template TKey of array-key
 * @template T
 * @extends  AbstractCollection<TKey,T>
 */
class Collection extends AbstractCollection
{ ... }

Links:

https://phpstan.org/blog/generics-in-php-using-phpdocs

https://psalm.dev/docs/annotating_code/templated_annotations/

https://stitcher.io/blog/php-generics-and-why-we-need-them

❤️ Simple PHP Code Parser

It based on code from “JetBrains/phpstorm-stubs” but instead of Php-Reflection we now use nikic/PHP-Parser, BetterReflection, phpDocumentor and PHPStan/phpdoc-parser internally. So, you can get even more information about the code. For example, psalm- / phpstan-phpdoc annotations or inheritdoc from methods.

Install:

composer require voku/simple-php-code-parser

Link:

voku/Simple-PHP-Code-Parser

More:


Example: get value from define in “\foo\bar” namespace

$code = '
  <?php
  namespace foo\bar;
  define("FOO_BAR", "Lall");
';

$phpCode = PhpCodeParser::getFromString($code);
$phpConstants = $phpCode->getConstants();

$phpConstants['\foo\bar\FOO_BAR']->value; // 'Lall'

Example: get information about @property phpdoc from a class

$code = '
  <?php
  /** 
   * @property int[] $foo 
   */
  abstract class Foo { }
';

$phpCode = PhpCodeParser::getFromString($code);
$phpClass = $phpCode->getClass('Foo');

$phpClass->properties['foo']->typeFromPhpDoc); // int

Example: get classes from a string (or from a class-name or from a file or from a directory)

$code = '
<?php
namespace voku\tests;
class SimpleClass {}
$obja = new class() {};
$objb = new class {};
class AnotherClass {}
';

$phpCode = \voku\SimplePhpParser\Parsers\PhpCodeParser::getFromString($code);
$phpClasses = $phpCode->getClasses();

var_dump($phpClasses['voku\tests\SimpleClass']); // "PHPClass"-object

Arrayy: A Quick Overview of map(), filter(), and reduce()

Arrayy: A PHP array manipulation library. Compatible with PHP 7+

The next examples are using the php array manipulation library “Arrayy” which is using generators internally for many operations.

https://github.com/voku/Arrayy

StringCollection::create(['Array', 'Array'])->unique()->append('y')->implode(); // Arrayy


map: transform all values in the collection

StringCollection::create(['foo', 'Foo'])->map('mb_strtoupper'); 

// StringCollection['FOO', 'FOO']

filter: pass all values to the truth test

$closure = function ($value) {
    return $value % 2 !== 0;
}
IntCollection::create([1, 2, 3, 4])->filter($closure); 

// IntCollection[0 => 1, 2 => 3]

reduce: transform all values into a new result

IntCollection::create([1, 2, 3, 4])->reduce(
    function ($carry, $item) {
        return $carry * $item;
    },
    1
); 

// IntCollection[24]

Modern PHPDoc Annotations

We will start very simple with PhpStorm and default PHPDoc, then we will increase the complexity step by step until we have auto-completion for array keys directly from the database with generics, immutable and type safety support.

1.0 PhpStorm & auto-generate PHPDoc blocks

„For documentation comments, PhpStorm provides completion that is enabled by default. PhpStorm creates stubs of „PHPDoc blocks“ when you type the /** opening tag and press Enter, or press Alt+Insert and appoint the code construct (a class, a method, a function, and so on) to document. Depending on your choice, PhpStorm will create the required tags or add an empty documentation stub.“

https://www.jetbrains.com/help/phpstorm/phpdoc-comments.html

Code:

/**
 * @param array $row
 *
 * @return array
 */
abstract function formatRow(array $row): array;

1.1 Return $this|static|self

It‘s quite annoying that php itself currently only have „self“ as return type (https://wiki.php.net/rfc/static_return_type) for the current class. Because of „late static binding“ you can use „static“ in your code to refer to the class a method was actually called on, even if the method is inherited. But in PHPDoc you can already use:

  • @return $this: if you really return $this (e.g. for fluent interface)
  • @return static: refer to the class a method was actually called on
  • @return self: refer to the class a method was written in

Code:

/**
 * @return static
 */
abstract function getFoo(): self;

1.2 New (and not that new) Array Syntax

PhpStorm and (PHPStan & Psalm) are supporting some new (and some not that new) array syntax for PHPDoc types, but for now PhpStorm will not auto-generate this types. 

Examples:

  • int[]: an array with only INT values – [1, 4, 6, 8, 9, …]
  • array<int, int>: an array with only INT values – [4 => 1, 8 => 4, 12 => 6, …]
  • string[]: an array with only STRING values – [„foo“, „bar“, …]
  • array<int, string>: an array with only STRING values – [4 => „foo“, 8 => „bar“, …]
  • Order[]: an array with only „Order“-Object values – [Order, Order, …]
  • array<int|string, Order>: an array with INT or STRING as key and „Order“-Object values – [4 => Order, ‘foo‘ => Order, …]
  • array<int|string, mixed>: an array with INT or STRING as key and mixed as values – [1 => 1, 4 => „foo“, 6 => \stdClass, …]
  • array<int, array<int, string>>: an array with INT as key and and an array (with INT as key and string as value) as values – [1 => [1 => „foo“], 4 => [1 => 4], …]
  • array<int, string[]>: an array with INT as key and and an array (with INT as key and string as value) as values – [1 => [„foo“, „lall“], 4 => [„öäü“, „bar“], …]
  • array{output: string, debug: string}: an array with the key “output” and “debug”, the values are STRING values – [‘output’ => ‘foo’, ‘debug’ => ‘bar’]
  • array<int, array{output: string, debug: string}>: an array with the key “output” and “debug”, the values are STRING values – [1 => [‘output’ => ‘foo’, ‘debug’ => ‘bar’], 3 => [‘output’ => ‘foo’, ‘debug’ => ‘bar’], …]

Examples (@psalm-* || @phpstan-*): PHPStan can also use “psalm-*” prefixed annotations and Psalm understands “phpstan-*” annotations.

  • list<array{output: string, debug: string}>: an array with the key “output” and “debug”, the values are STRING values – [0 => [‘output’ => ‘foo’, ‘debug’ => ‘bar’], 1 => [‘output’ => ‘foo’, ‘debug’ => ‘bar’], …]

list: represents continuous, integer-indexed arrays (always start from index zero) like: [“red”, “yellow”, “blue”] 

Live-Examples:

Psalm: https://psalm.dev/r/922d4ba5b1

PHPStan: https://phpstan.org/r/ce657ef4-9f18-46a1-b21a-e51e3a0e6d2d

Code:

/**
 * @param array<int|string, mixed> $row
 *
 * @return array<int|string, mixed>
 */
abstract function formatRow(array $row): array;

PhpStorm support?: Sadly PhpStorm did not have good support for these types, so that you often have to add „@psalm-*“ PHPDoc comments. For example PhpStorm will accept “array<int, Order>” but PhpStorm will not understand the PHPDoc, so that you need to add e.g. “@param Order[] $order” and “@psalm-param array<int, Order> $order”. 

Examples for PhoStorm + PHPStan || Psalm: 

/**
* @param Order[] $order
* @psalm-param array<int, Order> $order
*
* @return void
*/
public function fooOrder($order): void { ... }

// you could also use "..." here

/**
* @param Order ...$order
*
* @return void
*/
public function fooOrder(Order ...$order): void { ... }
/**
* @param int $foo_id
*
* @return Foo[]|Generator
* @psalm-return Generator&iterable<Foo>
*/
abstract function fetchYieldByFoo($foo_id): Generator;

1.3 Dynamic Autocompletion (+ data from your database) via deep-assoc-completion

If you have a method e.g. “formatRow($row)” you can use “getFieldArray()[0]” (data from the database – you have to connection the IDE with your database and your queries need to be analyzable by PhpStorm (take a look at the next screenshot) and combine static data from “getHeaderFieldArray()”, so that you have auto-completion from different sources.

Code:

/**
 * @param array<int|string, mixed> $row = $this->getFieldArray()[0] + $this->getHeaderFieldArray()
 *
 * @return array<int|string, mixed>
 */
abstract function formatRow(array $row): array;

more information + examples: https://github.com/klesun/deep-assoc-completion

1.4 Immutability Check via Static Code Analyses (via psalm)

And there is even more. :) You can add PHPDoc annotation that will check if you really use immutable classes or at least methods. Please read more here: https://psalm.dev/articles/immutability-and-beyond

Code:

/**
 * @param array<int|string, mixed> $row = $this->getFieldArray()[0] + $this->getHeaderFieldArray()
 *
 * @return array<int|string, mixed>
 *
 * @psalm-mutation-free
 */
abstract function formatRow(array $row): array;

Live-Example:

– Psalm: https://psalm.dev/r/5bac0a9a07

1.5 Generics in PHP via Static Code Analyses

We can also use Generics via code annotations. PHPStan & Psalm both support it, but Psalm’s support is more feature complete and both tools can use the „@psalm-“-syntax. Here comes some simple examples.

array_last: Will return the last array element from the $array (type: TLast) or the $fallback (type: TLastFallback). We tell the function that the types comes from the input parameters and that the input is an array of TLast or TLastFallback from the fallback.

/**
 * @param array<mixed> $array
 * @param mixed             $fallback <p>This fallback will be used, if the array is empty.</p>
 *
 * @return mixed|null
 *
 * @template TLast
 * @template TLastFallback
 * @psalm-param TLast[] $array
 * @psalm-param TLastFallback $fallback
 * @psalm-return TLast|TLastFallback
 */
function array_last(array $array, $fallback = null)
{
    $key_last = \array_key_last($array);
    if ($key_last === null) {
        return $fallback;
    }
return $array[$key_last]; }

array_first: Will return the first array element from the $array (type: TFirst) or the $fallback (type: TFirstFallback). We tell the function that the types comes from the input params and that the input is an array of TFirst or TFirstFallback from the fallback.

/**
 * @param array<mixed> $array
 * @param mixed             $fallback <p>This fallback will be used, if the array is empty.</p>
 *
 * @return mixed|null
 *
 * @template TFirst
 * @template TFirstFallback
 * @psalm-param TFirst[] $array
 * @psalm-param TFirstFallback $fallback
 * @psalm-return TFirst|TFirstFallback
 */
function array_first(array $array, $fallback = null)
{
    $key_first = array_key_first($array);
    if ($key_first === null) {
        return $fallback;
    }
return $array[$key_first]; }

So we can define „Templates“ and map input arguments on that types, this can be even more complex if you use it in a class context and you map the „Templates“ on class properties. But the logic will be the same.

Here is a more complex example: https://github.com/voku/Arrayy/blob/master/src/Collection/CollectionInterface.php

PhpStorm support?: Noop, sadly we need to hack this via „PHPSTORM_META“, so here is an example:

  • override(\array_filter(0), type(0)); // suppose first parameter type is MyClass[] then return type of array_filter will be MyClass[]
  • override(\array_reduce(0), elementType(0)); // suppose first parameter type is MyClass[] then return type of array_reduce will be MyClass

Read more here:

2.0 Resume

It‘s not perfect, and type check and auto-completion only with PHPDoc is not really what I expected for the year 2020. But it‘s working and I hope PhpStorm will bring more support for the new types annotations in the future.

More Links:

 

PHP: Arrays zusammenzuführen

In den folgenden Beispielen werden Standard-Funktionen von PHP gezeigt, um .

Ausgangswerte:

$array1 = [1 => 'one', 2 => 'two', 'foo' => 'bar1'];

$array2 = [3 => 'three', 4 => 'four', 6 => 'six', 'foo' => 'bar2'];

Wenn man Arrays mit “+” verbindet, werden die Werte in der Reihenfolge in welcher man diese Verbindet in das neue Array übernommen. Dabei sollte man jedoch beachten, dass gleiche Schlüssel (keys) nicht überschrieben werden.

$array2 + $array1;

—>

array
(
    [3] => three    // array2
    [4] => four     // array2
    [6] => six      // array2
    [foo] => bar2   // array2
    [1] => one      // array1
    [2] => two      // array1
)

Hier ein zweites Beispiel mit ‘+’, nun haben wir die ensprechenden Arrays jedoch umgekehrt, so dass der ‘foo’-Wert vom ersten Array behalten wird.

$array1 + $array2;

—>

array
(
    [1] => one      // array1
    [2] => two      // array1
    [foo] => bar1   // array1
    [3] => three    // array2
    [4] => four     // array2
    [6] => six      // array2
)

Diese kleine “foreach”-Schleife ist ein nachbau der ‘+’-Methode. Auch hier werden neue Werte angefügt, alte Werte jedoch behalten.

$union = $array1;
foreach ($array2 as $key => $value) {
  if (array_key_exists($key, $union) === false) {
    $union[$key] = $value;
  }
}

—>

array
(
    [1] => one      // array1
    [2] => two      // array1
    [foo] => bar1   // array1
    [3] => three    // array2
    [4] => four     // array2
    [6] => six      // array2
)


Und auch diese “foreach”-Schleife werden die Arrays vertauscht, so dass die Werte von ‘array2’ bestehen bleiben.

$union = $array2;
foreach ($array1 as $key => $value) {
  if (array_key_exists($key, $union) === false) {
    $union[$key] = $value;
  }
}

—>

array
(
    [3] => three    // array2
    [4] => four     // array2
    [6] => six      // array2
    [foo] => bar2   // array2
    [1] => one      // array1
    [2] => two      // array1
)

Die folgende PHP-Funktion (array_replace()) behält die Reihenfolge von ‘array1’, ersetzt jedoch Schlüssel (keys) welche ebenfalls in ‘array2’ vorkommen mit dessen Werten.

array_replace($array1, $array2);

—>

array
(
    [1] => one      // array1
    [2] => two      // array1
    [foo] => bar2   // array2 (position from array1)
    [3] => three    // array2
    [4] => four     // array2
    [6] => six      // array2
)

Hier wird ebenfalls ‘array_replace()’ verwendent, jedoch sind ‘array1’ und ‘array2’ wieder vertauscht und auch hier werden die Schlüssel (keys) beibehalten und die Position von ‘foo’ wird beibehalten.

array_replace($array2, $array1);

—>

array
(
    [3] => three    // array2
    [4] => four     // array2
    [6] => six      // array2
    [foo] => bar1   // array1 (position from array2)
    [1] => one      // array1
    [2] => two      // array1
)

Die Funktion ‘array_merge()’ vergibt neue Schlüssel (keys) für indizierte Arrays (0,1,2,3…). Somit fängt das neue Array nun mit dem Schlüssel “0” an.

array_merge($array1, $array2);

—>

array
(
    [0] => one      // array1 (with a new key)
    [1] => two      // array1 (with a new key)
    [foo] => bar2   // array2 (position from array1)
    [2] => three    // array2 (with a new key)
    [3] => four     // array2 (with a new key)
    [4] => six      // array2 (with a new key)
)

Auch hier wurden die Arrays wieder vertauscht und auch hier wurden die numerischen Schlüssel durch neue ersetzt.

array_merge($array2, $array1);

—>

array
(
    [0] => three    // array2 (with a new key)
    [1] => four     // array2 (with a new key)
    [2] => six      // array2 (with a new key)
    [foo] => bar1   // array1 (position from array2)
    [3] => one      // array1 (with a new key)
    [4] => two      // array1 (with a new key)
)

Die PHP-Library “Arrayy” (https://github.com/voku/Arrayy) …

Arrayy::create($array1)->mergePrependKeepIndex($array2);

—>

Arrayy {
  ["array":protected]=>
  array(6) {
    [1]=> one
    [2]=> two
    [foo]=> bar2
    [3]=> three
    [4]=> four
    [6]=> six
  }
}

Arrayy::create($array1)->mergePrependNewIndex($array2);

—>

Arrayy {
  ["array":protected]=>
  array(6) {
    [0]=> three
    [1]=> four
    [2]=> six
    [foo]=> bar1
    [3]=> one
    [4]=> two
  }
}

Links:

Blackfire PHP-Profiler: Fire up the Performance

Am Wochenende habe ich mal wieder ein neues Tool ausprobiert: “Blackfire” ist ebenso wie “Insight” von SensioLabs entwickelt und kann die Performance einer PHP-Anwendung “on the fly” analysieren und visualisieren.

Die Installation besteht aus folgenden Komponenten:

  • Probe: dies ist die PHP-Extension welche wir auf dem Server installieren
  • Agent: Dies ist ein Programm, welches ebenfalls auf dem Server installiert wird und die Performance-Daten zu blackfire.io weiterleitet, wo diese dann visualisiert werden
  • Client (optional): ein CLI-Tool um PHP-Profiling auf der Kommandozeile auszuführen
  • Companion: dies ist eine Chrome-Extension, welche auf Knopfdruck das PHP-Profiling ausführt
  • Website: die blackfire.io Webseite zur Darstellung der Ergebnisse

Die Installationsanleitung ist innerhalb von zirka 5 Minuten abgearbeitet und schon kann man schnell und bequem die Leistung / Performance von Änderungen testen und die entsprechenden Ergebnisse miteinander vergleichen.

blackfire.io
blackfire.io: Beispiel-Profile von “http://moelleken.org

 

PS: wer noch mehr Information benötigt sollte sich Xdebug lokal installieren bzw. aktivieren und die Profile-Daten anschließend via WinCacheGrind (Windows) oder direkt via KCachegrind (Linux) auswerten und visualisieren.

KCachegrind
KCachegrind

 

DO EPIC SHIT!

Slides | Demo (source)

Auf der OpenRheinRuhr (Messe mit Kongress rund um das Thema “Freie Software”) habe ich meinen ersten öffentlichen Vortrag gehalten. Dazu habe ich das Thema “Open Source Workflow für Webentwickler” gewählt und mit dem doch sehr einprägsamen Titel “DO EPIC SHIT!” angekündigt.

B16GnDZIcAA3aRb

Gegen alle Erwartungen bin ich pünklich angekommen, auch wenn die Bahn (GDL) gestreikt hat. Also hatte ich noch etwas Zeit, um noch einen `git commit` vorzubereiten, welcher dann live in dem Vortrag automatisch via Jenkins getestet und deployed werden konnte.

Und auch wenn ich den Vortrag nicht so beenden konnte wie ursprünglich geplant, da ich die Zeit irgendwie falsch eingeteilt hatte, hoffe ich trotzdem einiges nützliches gezeigt zu haben. Beim nächsten mal sollte ich dies wohl vor “echtem” Publikum testen, da die Zeit dann anscheinend anders verläuft. ;) Einige Erklärungen und Beispiele von der Demo-Webseite musste ich daher unterschlagen und reiche diese Infos im folgenden nach:

Backend:

Frontend:

Extras:

PS: Ich werde heute wieder auf der OpenRheinRuhr sein, da auch das heutige Programm sehr interessante Vorträge und Workshops biete. z.B.: DockerSaltStackImageMagick. Gegebenenfalls sieht man sich dort :) wünsche allen Beteiligten viel Spaß!

Web Development mit Linux (Video)

Im folgenden Video zeige ich kurz (~ 5 min.) wie meine Toolchain im Live-Betrieb aussieht, dabei nutze ich unter anderem Sublime Text, PHP, Twig, Grunt, Sass, Compass, LiveReload und ein paar Funktionen aus den “dofiles” (z.B. phpserver).

 

Wer den Beispiel-Code aus dem Video selber ausprobieren möchte, hier die Zusammenfassung:

sudo apt-get install git

cd ~
git clone https://github.com/voku/dotfiles/
cd dotfiles/
./firstInstall.sh
./bootstrap.sh
cd ~
vim ~/.extra #1

cd ~
mkdir Projects/
git clone https://github.com/voku/twig-wrapper-example/
cd twig-wrapper-example/
npm install
grunt watch

cd ~/Projects/twig-wrapper-example/
phpserver

#1 füge deine persönlichen Git-Einstellungen hier hinzu

 

Wer mehr Infos oder Erklärungen zu den hier verwendeten Tools haben möchte, sollte sich einmal folgende Videos anschauen: suckup.de/howto/html/moderner-build-development-workflow-via-bower-grunt-yeoman/

 

Twig – PHP

Als erstes möchte ich hier klären was “Twig” ist und wie man diese PHP-Bibliothek verwendet.

Was ist Twig?

Twig ist eine Open Source Template-Engine für PHP und wird z.B. von Symfony verwendet. Damit ist es möglich die Programmierung vom Layout zu trennen und Projekte somit übersichtlicher und sicherer zu erstellen. Zudem kann man Twig relativ einfach erweitern und neue Funktionen oder Filter hinzufügen. Außerdem ist die Dokumentation wirklich gut und die Einarbeitungszeit ist sehr kurz.

 

Schnelle Installation

Damit man einen schnellen Einstig in Twig bekommt, habe ich eine kleine Wrapper-Klasse geschrieben und in einem zweiten Projekt “Twitter Bootstrap” als Twig-Beispiel -Template integriert.

git clone https://github.com/voku/twig-wrapper-example/

Das Projekte ist mit Gunt + SASS + Bower + Composer etc. aufgesetzt, jedoch habe ich alle Vendor-Dateien mit in dem Repository eingecheckt, so dass man keine komplette Toolchain benötigt um die folgenden Beispiele auszuprobieren.

PS: um das Projekt zu updaten bzw. weiterzuentwickeln kann man folgende Befehle ausführen:

cd twig-wrapper-example/
rm -rf vendor/
rm composer.lock
npm install
bower install
composer install
grunt build
grunt watch

 

Syntax

Die Allgemeine-Syntax lässt sich in “output”, “function” und “comment” unterteilen.

output” ->  {{ … }}  -> um Variablen in das Template einzufügen

function” -> {% … %} -> um Funktionen auszuführen

comment” -> {# … #} -> um einen Kommentar einzufügen, welche nur im Twig sichbar ist (nicht im späterem “html”-output)

Variablen

Man kann sowohl Arrays, einfache Variablen oder ganze Objekte an Twig übergeben.

z.B.:

$object = new Object();
$twig->assign('object', $object);
$array = array(1,2,3,4,5);
$twig->assign('array', $array);
$string = 'test';
$twig->assign('string', $string);

Zudem kann man auch Variablen in einem Twig-Template definieren:

{% set totalimages = 4 %}

Filter

Auf der Kommandozeile ist man bereits an Pipes ( “|” ) gewöhnt und kann dies nun auch bei der Entwicklung nutzen. :)

{% set totalimages = object.images | length %}
{{ array[1] | striptags | raw }}

Kontrollstrukturen

“if”-Bedingungen werden wie folgt geschrieben:

{% if (name == "foo") or (name == "bar") %}
    {{ name }}!!!
{% elseif name == "test" %}
    {{ name }} -> was a test
{% else %}
    {{ name }}
{% endif %}

“loops” in Twig: for

{% for asset in headerObject %}
  <img src="{{ asset.url }}">
  <p>{{ asset.caption }}</p>
  {% if loop.index0 is divisibleby(2) %}
    <hr />
  {% endif %}
{% endfor %}

PS: außerdem kann man wie im vorherigen Beispiel – “loop” nutzen, um den Anzahl von aktuellen Durchläufe zu analysieren

 

extends

Eine Hauptfunktionalität ist die Twig-Funktion “extends“. Mit dieser Funktion kann man sein Template erweitern und zuvor definierte Bereiche (block – endblock) wiederum ersetzten.

{%extends “base.twig” %}

base.twig -> index.twig

Der vorherige Befehl bewirkt in der “index.twig” Datei, dass das angegebene Template erweitert wird. Dabei ist es sehr hilfreich möglichst viel HTML-Code in einem Basis-Twig unterzubringen. Anders wie bei vielen anderen PHP-Projekten sollte man nicht so oft via “include” inkludieren, sondern bestimmte Bereiche (blocks) im “base.twig” festlegen und diese mit Inhalten befüllen, erweitern oder leeren.

 

include

Die Funktionalität “include” lässt sich einsetzten um Template-Komponenten (z.B.: einen Slider) an mehreren Stellen einzufügen. Man hat die Möglichkeit beim “include”-Aufruf Variablen zu übergeben, jedoch kann man keine “blocks” von bereits inkludierten Templates mehr ändern.

{% include “inc_carousel.twig” %}

base.twig -> inc_carousel.twig

 

embed

Beim “embed” handelt es sich um eine Mischung aus extending & including, so kann man innerhalb des embed-Aufrufes darin befindliche “blocks” ersetzten.

{% embed “content_sidebar.twig” %}

index.twig -> content_sidebar.twig

 

Twig_Extension

Wem ein bestimmter Filter oder Funktion fehlt, kann dies sehr einfach in Twig  integrieren z.B. -> PluginHtml.php

$twig->addExtension(new PluginHtml());

 

Links

http://knpuniversity.com/screencast/twig/basics | Basics – Video
http://twig.sensiolabs.org/ | Dokumentation

Einführung: PHP-Variablen und der Garbage Collector

In diesem Blog-Post möchte ich erklären, was technisch hinter einer Variable in PHP steckt und wann PHP den Speicher dieser Variablen wieder freigibt.

Der PHP Quellcode?

Im Alltag schaut man doch ehr selten (nie) in den eigentlichen Quellcode von PHP. Dies sollten wir an dieser Stelle nachholen. -> https://github.com/php/php-src/tree/PHP-5.5

Info: Auf der folgenden Seite kann man den PHP Quelltext einfach nach bestimmten z.B.: Funktionen durchsuchen: http://lxr.php.net

Ich habe mich hier für den Quelltext von PHP 5.5 entschieden, da diese Version auf meinen lokalen PC läuft und ich die folgenden Tests mit dieser Version durchführen werde.

PHP Quellcode – Struktur: Hier gibt es zwei Hautbestandteile von PHP, mit welchen wir uns weiter beschädigen werden. Aufgeteilt sind diese in den folgende zwei Verzeichnissen.

– Zend: (www.php.net/manual/en/langref.php) Die Zend Engine, stellt die Laufzeitumgebung für PHP zur Verfügung. In diesem Verzeichnis werden somit alle “language level”-Funktionen von PHP bereitgestellt wie z.B. Variablen, Syntax-Analyse, Code-Ausführung und Fehlerbehandlung.

– ext: (www.php.net/manual/en/funcref.php) Extensions, stellt alle einzel Funktionen von PHP bereit. (z.B. strpos, substr, PDO, SplFixedArray etc.)

Intern stellt PHP jeder Variable als sogenannte “ZVALs” da. Dies ist unter anderen nötig, da der PHP-Kern in C geschrieben ist, C jedoch keine dynamische Typisierung wie in PHP zulässt. Somit bedient man sich einer Art Wrapper, welcher verschiedene Werte beinhalten kann.

struct _zval_struct {
  /* Variable information */
  zvalue_value value;             /* value */
  zend_uint refcount__gc;
  zend_uchar type;                /* active type */
  zend_uchar is_ref__gc;
};

Was steck in einer zval-Struktur?

value: http://lxr.php.net/xref/PHP_5_5/Zend/zend.h#321

typedef union _zvalue_value {
    long lval;                   /* long value */
    double dval;                /* double value */
    struct {
        char *val;
        int len;
    } str;
    HashTable *ht;              /* hash table value */
    zend_object_value obj;
} zvalue_value;

Wir sehen, dass der “value” in einer PHP-Variable (zval) mehrere Variablentpyen (Zustände) beinhaltet. Daher kann eine PHP-Variable sowohl einen int-Wert, als auch ein Array beinhalten.

z.B.:
$foo = (int) 3;
$foo = array(3);

C

PHP

long

int, boolean, resource

double

float

str

string

hashtable

array

zend_object_value

object

type: http://lxr.php.net/xref/PHP_5_5/Zend/zend.h#578

/* data types */
/* All data types <= IS_BOOL have their constructor/destructors skipped */
#define IS_NULL     0
#define IS_LONG     1
#define IS_DOUBLE   2
#define IS_BOOL     3
#define IS_ARRAY    4
#define IS_OBJECT   5
#define IS_STRING   6
#define IS_RESOURCE 7
#define IS_CONSTANT 8
#define IS_CONSTANT_ARRAY   9
#define IS_CALLABLE 10

/* Ugly hack to support constants as static array indices */
#define IS_CONSTANT_TYPE_MASK       0x00f
#define IS_CONSTANT_UNQUALIFIED     0x010
#define IS_CONSTANT_INDEX           0x080
#define IS_LEXICAL_VAR              0x020
#define IS_LEXICAL_REF              0x040
#define IS_CONSTANT_IN_NAMESPACE    0x100

Da wir sovor gesehen haben, dass das “value”-Feld verschiedene Typen von Variablen beinhalten kann, wird hier festgelegt um welchen Type es sich hier handelt. z.B.: zval.type = IS_LONG

is_ref: 0 || 1 http://www.phpinsider.com/download/PHP5RefsExplained.pdf
Dieses Feld wird auf “1” gesetzt falls es sich bei der Variable um eine Referenz (z.B.: &$foo) handelt.

refcount: http://www.php.net/manual/en/features.gc.refcounting-basics.php
Dieses Feld ist ein Zähler für die Anzahl von PHP-Variablen, welche zu dem internen zval referenzieren, so kann der PHP Garbage Collector entscheiden, wann die entsprechende Variable nicht mehr benötigt wird.

z.B.:
$a= new A;    // 1 Referenz
$b = $a;         // 2 Referenzen
unset( $a );   // 1 Referenz
unset( $b);    // 0 Referenzen

Größe von “zval”?

Auf folgender Webseite wurden bereits mit PHP 5.3 getestet, wie viel Speicher für 100000 Integer-Werten in einem Array benötigt werden. -> http://nikic.github.io/2011/12/12/How-big-are-PHP-arrays-really-Hint-BIG.html

                             |  64 bit   | 32 bit

zval                         |  24 bytes | 16 bytes
+ cyclic GC info             |   8 bytes |  4 bytes
+ allocation header          |  16 bytes |  8 bytes
===================================================
zval (value) total           |  48 bytes | 28 bytes
===================================================
bucket                       |  72 bytes | 36 bytes
+ allocation header          |  16 bytes |  8 bytes
+ pointer                    |   8 bytes |  4 bytes
===================================================
bucket (array element) total |  96 bytes | 48 bytes
===================================================
total total                  | 144 bytes | 76 bytes

144 bytes * 100000 = 13.73 MB

Test mit PHP 5.5 (32-Bit)

$int = 0;
Speichergröße: 176 bytes

(refcount=1, is_ref=0),int 0

$null = null;
Speichergröße: 184 bytes

(refcount=1, is_ref=0),null

Da es für “null” keinen Eintrag im zvalue_value gibt, wird dieser Wert seperat gespeichert und benötigt somit inital mehr Speicher als 0.

$string = ”;
Speichergröße: 200 bytes

(refcount=1, is_ref=0),string '' (length=0)

$string = ‘1234567’;
Speichergröße: 200 bytes

(refcount=1, is_ref=0),string '1234567' (length=7)

$string = ‘12345678’;
Speichergröße: 208 bytes

(refcount=1, is_ref=0),string '1234567' (length=8)

$string = ‘0123456789’;
Speichergröße: 208 bytes

(refcount=1, is_ref=0),string '1234567' (length=10)

Wir sehen, dass PHP jeweills 1 byte (8 bit) benötigt, um ein Zeichen für einen String zu Speichern und diese zu jeweills 8 bytes zusammenfasst. So bleiden im letzten Beispiel 192 (208 – 16) bytes übrig, welche PHP benötigt um die entsprechende Variable anzulegen.

$array = range(1, 100000);
Speichergröße: 8524576 bytes => 8.12966919 megabytes

(refcount=1, is_ref=0), array (size=100000)
  0 => (refcount=1, is_ref=0),int 1
  1 => (refcount=1, is_ref=0),int 2
  2 => (refcount=1, is_ref=0),int 3
  3 => (refcount=1, is_ref=0),int 4
  [...]

 

PHPs Garbage Collector

Quellcode für den Test: test4.php

start:                                88 bytes 
array:                     8524592 bytes 
function1-begin:     8524608 bytes 
function1-end:      17049016 bytes 
array-test4:             8524536 bytes 
function2-begin:      8524552 bytes 
function2-end:         8524616 bytes 
array-test4_ref:       8524552 bytes 
end:                         8524552 bytes 

Wir sehen, dass PHP bei der ersten Funktion mit Parameterübergabe (ohne Referenz) das entsprechende Array kopiert, da es sich hier um eine neue Variable handelt, welche in der Funktion verarbeite wird und zurückgegeben wird. Zusätzlich können wir hier beobachten wann PHP die Variable kopiert und zwar erst wenn diese Verändert wird (copy-on-write).

 

Zusammenfassung:

Ich glaube es ist Zeit für eine erste Zusammenfassung von dem was wir bisher aus den PHP Quelltext und den ersten kleinen Tests sehen konnten.

1.) PHP behandelt Variablen intern als Struktur von Variablen (zval_struct -> zval).

2.) Diese Struktur beinhaltet nicht nur den aktuellem Wert und den Type, sondern auch die Anzahl wie oft diese Variable verwendet wird und ob es sich dabei um eine Referenz (&) handelt. 

3.) PHPs Garbage Collector kann somit nicht mehr benötigte Variablen selbständig aus dem Speicher löschen.

 

Quellen:
http://www.php.net/manual/en/internals2.variables.intro.php
http://www.php.net/manual/en/features.gc.refcounting-basics.php
http://www.php.net/manual/en/function.debug-zval-dump.php

http://code.stephenmorley.org/php/references-tutorial/
http://www.developerknowhow.com/inside-the-php-engine-integers-and-their-zval/
http://webandphp.com/how-php-manages-variables
http://wiki.selfhtml.org/wiki/Artikel:PHP/
http://www.sitepoint.com/better-understanding-phps-garbage-collection/