Prepare your PHP Code for Static Analysis

Three years ago I got a new job as PHP developer, before that I called myself web developer because I build ReactJS, jQuery, CSS, HTML, … and PHP  stuff for a web agency. So now I am a full-time PHP developer and I converted a non typed  (no PHPDoc + no native types) project with ~ 10.000 classes into a project with ~ 90% type coverage. Here is what I have learned.

1. Write code with IDE autocompletion support.

If you have autocompletion in the IDE most likely the Static Analysis can understand the code as well. 

Example:

bad:

->get('DB_Connection', true, false);

still bad:

->get(DB_Connection::class);

good:

getDbConnection(): DB_Connection

2. Magic in Code is bad for the long run!

Magic methods (__get, __set, …) for example can help to implement new stuff very fast, but the problem is nobody will understand it, you will have no autocompletion, no refactoring options, other developers will need more time to read and navigate in the code and in the end it will cost you much more time than you can save with it.

3. Break the spell on Magic Code …

… by explaining to everyone (Devs > IDE > Tools) what it does.

Example 1:

We use a simple Active Record Pattern, but we put all SQL stuff into the Factory classes, so that the Active Record class can be simple. (Example) But because of missing support for Generics we had no autocompletion without adding many dummy methods into the classes. So one of my first steps was to introduce a “PhpCsFixer” that automatically adds the missing methods of the parent class with the correct types via “@method”-comments into these classes. 

Example 2:

Sometimes you can use more modern PHPDocs to explain the function. Take a look at the “array_first” function in the linked Post.

Example 3:

/**
* Return an array which has the Property-Values of the given Objects as Values.
*
* @param object[] $ObjArray
* @param string $PropertyName
* @param null|string $KeyPropertyName if given uses this Property as key for the returned Array otherwise the keys from the
* given array are used
*
* @throws Exception if no property with the given name was found
*
* @return array
*/
function propertyArray($ObjArray, $PropertyName, $KeyPropertyName = null): array {
// init
$PropertyArray = [];

foreach ($ObjArray as $key => $Obj) {
if (!\property_exists($Obj, $PropertyName)) {
throw new Exception('No Property with Name ' . $PropertyName . ' in Object Found - Value');
}

$usedKey = $key;
if ($KeyPropertyName) {
if (!\property_exists($Obj, $KeyPropertyName)) {
throw new Exception('No Property with Name ' . $PropertyName . ' in Object Found - Key');
}
$usedKey = $Obj->{$KeyPropertyName};
}

$PropertyArray[$usedKey] = $Obj->{$PropertyName};
}

return $PropertyArray;
}

Sometimes it’s hard to describe the specific output types, so here you need to extend the  functions of your Static Code Analyze Tool, so that it knows what you are doing. ⇾ for example here you can find a solution for PHPStan ⇽  but there is still no support for the IDE and so maybe it’s not the best idea to use magic like that at all. And I am sure it’s more simple to use specific and simple methods instead:  e.g. BillCollection->getBillDates()

4. Try to not use strings for the code.

Strings are simple and flexible, but they are also bad for the long run. Mostly strings are used because it looks like a simple solution, but often they are redundant, you will have typos everywhere and the IDE and/or Static Analysis can’t analyze them because it’s just text.

Example:

bad: 

AjaxEditDate::generator($bill->bill_id, $bill->date, 'Bill', 'date');
  • “Bill” ⇾ is not needed here, we can call e.g. get_class($bill) in the “generator” method
  • “date” ⇾ is not needed here, we can fetch the property name from the class
  • “$bill->bill_id” ⇾ is not needed here, we can get the primary id value from the class

good:

AjaxEditDate::generator($bill, $bill->m()->date);

5. Automate stuff via git hook and check it via CI server.

Fixing bad code is only done if you disallow the same bad code for the future. With a pre-commit hook for git it’s simple to run these checks, but you need to check it again in the CI server because the developers can simply skip these checks.

Example:

I introduced a check for disallowing global variables (global $foo && $GLOBALS[‘foo’]) via “PHP_CodeSniffer”. 

Links:

6. Use array shapes (or collections) if you need to return an array, please.

Array shapes are like arrays but with fixed keys, so that you can define the types of each key in the PHPDocs.

You will have autocompletion for the IDE + all other devs can see what the method will return + you will notice if you’re better retuning an object because it will be very hard to describe the output for complex data structures and Static Analysis can use and check the types. 

Example:

/**
* @return array{
* missing: array<ShoppingCartLib::TAB_*,string>,
* disabled: array<ShoppingCartLib::TAB_*,string>
* }
*/
private static function getShoppingCartTabStatus(): array {
...
}

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