PHPdoc – Definieren von Objekteigenschaften für ein Objekt der stdClass

Ich versuche herauszufinden, ob es möglich ist, PHPdoc zu verwenden, um die Objekteigenschaften zu definieren, die von einer Funktion oder einer Objektmethode zurückgegeben werden.

Angenommen, ich habe die folgende Klasse:

class SomeClass {
    public function staffDetails($id){

        $object = new stdClass();
        $object->type = "person";
        $object->name = "dave";
        $object->age = "46";        

        return $object;
    }
}

Jetzt ist es einfach genug, Eingabeparameter zu definieren.

 /**
 * Get Staff Member Details
 * 
 * @param   string  $id    staff id number
 * 
 * @return  object
 */

class SomeClass {
    public function staffDetails($id){
        $object = new stdClass();
        $object->type = "person";
        $object->name = "dave";
        $object->age = "46";        

        return $object;
    }
}

Die Frage ist, ob es etwas Ähnliches gibt, um Eigenschaften des Ausgabeobjekts (einer stdClass) zu definieren, das von der fraglichen Methode zurückgegeben wird. Damit ein anderer Programmierer diese Klasse nicht öffnen und manuell in die Methode schauen muss, um zu sehen, was das Rückgabeobjekt zurückgibt?

Hier ist es 4 Jahre später, und es scheint immer noch keine Möglichkeit zu geben, die Eigenschaften eines stdClass-Objekts wie ursprünglich in Ihrer Frage beschrieben zu kommentieren.

Sammlungen wurden in PSR-5 vorgeschlagen, aber das scheint abgeschossen worden zu sein: https://github.com/php-fig/fig-standards/blob/211063eed7f4d9b4514b728d7b1810d9b3379dd1/proposed/phpdoc.md#collections

Anscheinend gibt es nur zwei Möglichkeiten:

Option 1:

Erstellen Sie eine normale Klasse, die Ihr Datenobjekt darstellt, und kommentieren Sie die Eigenschaften.

class MyData
{
    /**
     * This is the name attribute.
     * @var string
     */
    public $name;

    /**
     * This is the age attribute.
     * @var integer
     */
    public $age;
}

Option 2:

Erstellen Sie ein Generikum Struct Geben Sie Klasse ein, wie von Gordon vorgeschlagen, und erweitern Sie sie als Ihr Datenobjekt, indem Sie die verwenden @Eigentum Anmerkung, um zu definieren, auf welche generischen Werte zugegriffen werden kann __get und __set.

class Struct
{
    /**
     * Private internal struct attributes
     * @var array
     */
    private $attributes = [];

    /**
     * Set a value
     * @param string $key
     * @param mixed $value
     */
    public function __set($key, $value)
    {
        $this->attributes[$key] = $value;
    }

    /**
     * Get a value
     * @param string $key
     * @return mixed
     */
    public function __get($key)
    {
        return isset($this->attributes[$key]) ? $this->attributes[$key] : null;
    }

    /**
     * Check if a key is set
     * @param string $key
     * @return boolean
     */
    public function __isset($key)
    {
        return isset($this->attributes[$key]) ? true : false;
    }
}

/**
 * @property string $name
 * @property integer $age
 */
class MyData extends Struct
{
    // Can optionally add data mutators or utility methods here
}

Sie haben nur zwei Möglichkeiten, die Struktur der Ergebnisklasse zu dokumentieren.

1.Man kann die Struktur in einem Kommentartext beschreiben. Zum Beispiel:

class SomeClass 
{
    /**
     * Getting staff detail.
     * Result object has following structure:
     * <code>
     * $type - person type
     * $name - person name
     * $age - person age
     * </code>
     * @param string $id staff id number
     *
     * @return stdClass
     *
     */
    public function staffDetails($id){
        $object = new stdClass();
        $object->type = "person";
        $object->name = "dave";
        $object->age = "46";
        return $object;
    }
}

2. Man kann einen Datentyp erstellen, der stdClass erbt und eine Anmerkung eines Ergebnisobjekts hat. Zum Beispiel:

/**
 * @property string $type Person type
 * @property string $name Person name
 * @property integer $age Person age
 */
class DTO extends stdClass
{}

Und verwenden Sie es in Ihren anderen Klassen

class SomeClass {

    /**
     * Getting staff detail.
     *
     * @param string $id staff id number
     *
     * @return DTO
     *
     */
    public function staffDetails($id){

        $object = new DTO();
        $object->type = "person";
        $object->name = "dave";
        $object->age = "46";

        return $object;
    }
}

Meiner Meinung nach ist dieser Weg besser als eine Beschreibung im Textkommentar, weil er den Code offensichtlicher macht

Wenn Sie PHP 7 verwenden, können Sie eine anonyme Klasse definieren.

class SomeClass {
    public function staffDetails($id){
        $object = (new class() extends stdClass {
                public /** @var string  */ $type;
                public /** @var string  */ $name;
                public /** @var int     */ $age;
            });

        $object->type = "person";
        $object->name = "dave";
        $object->age  = 46;        

        return $object;
    }
}

Es funktioniert für meine IDE (getestet in NetBeans)

Mit zum Beispiel json_decode Es ist schwieriger, stattdessen eigene Klassen zu verwenden stdClassaber in meinem Fall habe ich nur eine Dummy-Datei mit Klassendefinitionen erstellt, die wirklich nicht geladen ist, und ich füge eigene Klassen als hinzu @return (funktioniert für Intelephense auf vscode).

PHPdocObjects.php

/**
 * class only for PHPdoc (do not include)
 */
class Member {
    /** @var string */
    public $type;
    /** @var string */
    public $name;
    /** @var string */
    public $age;
}

/**
 * Other format
 *
 * @property string $type;
 * @property string $name;
 * @property string $age;
 */
class MemberAlt {}

SomeClass.php

 /**
 * Get Staff Member Details
 * 
 * @param   string  $id    staff id number
 * 
 * @return  Member  I'm in fact stdClass
 */

class SomeClass {
    public function staffDetails($id){
        $object = json_decode('{"type":"person","name":"dave","age":"46"}');
        return $object;
    }
}

Der Hack, den ich für die automatische Vervollständigung in PhpStorm verwende:

1. Erstellen Sie eine Metadatei, die einige Klassen enthält, um Ihre Strukturen zu beschreiben. Die Datei ist nie enthalten und Strukturen haben ihre eigenen Namensregeln, um sie nicht mit real existierenden Klassen zu verwechseln:

<?php
/*
meta.php
never included
*/

/**
 * @property string $type
 * @property string $name
 * @property string $age
 */
class StaffDetails_meta {}

2. Verwenden Sie die Metaklasse als Rückgabewert in Ihrem echten Code PHPDoc:

<?php
/*
SomeClass.php
eventually included
*/

class SomeClass
{
    
    /**
     * Get Staff Member Details
     * 
     * @param   string  $id    staff id number
     * 
     * @return StaffDetails_meta
     */
    public function staffDetails($id)
    {
        $object = new stdClass();
        $object->type = "person";
        $object->name = "dave";
        $object->age = "46";        

        return $object;
    }
}

3. Herzlichen Glückwunsch, dadurch wird Ihre IDE Ihren Code automatisch vervollständigen, wenn Sie so etwas wie eingeben würden (new SomeClass)->staffDetails('staff_id')->

PS: Ich weiß, fast 10 Jahre sind vergangen, aber immer noch aktuell