RetailCRM-Mirror/graphql-php
1
0
Fork 0
mirror of https://github.com/retailcrm/graphql-php.git synced 2025-02-06 07:49:24 +03:00
Code Issues Projects Releases Wiki Activity

Improving docblock comments

Browse Source
This commit is contained in:
Vladimir Razuvaev 2017-08-17 02:15:49 +07:00
parent b4d767bad6
commit 51e877bfba
8 changed files with 145 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
src/Error/Warning.php
View File

@ -18,11 +18,27 @@ final class Warning
static private $warningHandler;
/**
* Sets warning handler which (when set) will intercept all system warnings.
* When not set, trigger_error() is used to notify about warnings.
*
* @param callable|null $warningHandler
*/
public static function setWarningHandler(callable $warningHandler = null)
{
self::$warningHandler = $warningHandler;
}
/**
* Suppress warning by id (has no effect when custom warning handler is set)
*
* Usage example:
* Warning::suppress(Warning::NOT_A_TYPE)
*
* When passing true - suppresses all warnings.
*
* @param bool|int $suppress
*/
static function suppress($suppress = true)
{
if (true === $suppress) {
@ -35,6 +51,16 @@ final class Warning
}
}
/**
* Re-enable previously suppressed warning by id
*
* Usage example:
* Warning::suppress(Warning::NOT_A_TYPE)
*
* When passing true - re-enables all warnings.
*
* @param bool|int $enable
*/
public static function enable($enable = true)
{
if (true === $enable) {

9
src/Language/Parser.php
View File

@ -70,12 +70,12 @@ class Parser
/**
* Given a string containing a GraphQL value (ex. `[42]`), parse the AST for
* that value.
* Throws GraphQLError if a syntax error is encountered.
* Throws GraphQL\Error\SyntaxError if a syntax error is encountered.
*
* This is useful within tools that operate upon GraphQL Values directly and
* in isolation of complete GraphQL documents.
*
* Consider providing the results to the utility function: valueFromAST().
* Consider providing the results to the utility function: GraphQL\Utils\AST::valueFromAST().
*
* @param Source|string $source
* @param array $options
@ -94,12 +94,13 @@ class Parser
/**
* Given a string containing a GraphQL Type (ex. `[Int!]`), parse the AST for
* that type.
* Throws GraphQLError if a syntax error is encountered.
* Throws GraphQL\Error\SyntaxError if a syntax error is encountered.
*
* This is useful within tools that operate upon GraphQL Types directly and
* in isolation of complete GraphQL documents.
*
* Consider providing the results to the utility function: typeFromAST().
* Consider providing the results to the utility function: GraphQL\Utils\AST::typeFromAST().
*
* @param Source|string $source
* @param array $options
* @return ListTypeNode|NameNode|NonNullTypeNode

6
src/Language/Printer.php
View File

@ -42,6 +42,12 @@ use GraphQL\Utils\Utils;
class Printer
{
/**
* Prints AST to string. Capable of printing GraphQL queries and Type definition language.
*
* @param Node $ast
* @return string
*/
public static function doPrint($ast)
{
static $instance;

82
src/Language/Visitor.php
View File

@ -18,7 +18,7 @@ class VisitorOperation
class Visitor
{
/**
* Break visitor
* Returns marker for visitor break
*
* @return VisitorOperation
*/
@ -30,7 +30,9 @@ class Visitor
}
/**
* Skip current node
* Returns marker for skipping current node
*
* @return VisitorOperation
*/
public static function skipNode()
{
@ -40,7 +42,9 @@ class Visitor
}
/**
* Remove current node
* Returns marker for removing a node
*
* @return VisitorOperation
*/
public static function removeNode()
{
@ -105,23 +109,23 @@ class Visitor
* a new version of the AST with the changes applied will be returned from the
* visit function.
*
* var editedAST = visit(ast, {
* enter(node, key, parent, path, ancestors) {
* // @return
* // undefined: no action
* // false: skip visiting this node
* // visitor.BREAK: stop visiting altogether
* // null: delete this node
* $editedAST = Visitor::visit($ast, [
* 'enter' => function ($node, $key, $parent, $path, $ancestors) {
* // return
* // null: no action
* // Visitor::skipNode(): skip visiting this node
* // Visitor::stop(): stop visiting altogether
* // Visitor::removeNode(): delete this node
* // any value: replace this node with the returned value
* },
* leave(node, key, parent, path, ancestors) {
* // @return
* // undefined: no action
* // visitor.BREAK: stop visiting altogether
* // null: delete this node
* 'leave' => function ($node, $key, $parent, $path, $ancestors) {
* // return
* // null: no action
* // Visitor::stop(): stop visiting altogether
* // Visitor::removeNode(): delete this node
* // any value: replace this node with the returned value
* }
* });
* ]);
*
* Alternatively to providing enter() and leave() functions, a visitor can
* instead provide functions named the same as the kinds of AST nodes, or
@ -130,51 +134,57 @@ class Visitor
*
* 1) Named visitors triggered when entering a node a specific kind.
*
* visit(ast, {
* Kind(node) {
* Visitor::visit($ast, [
* 'Kind' => function ($node) {
* // enter the "Kind" node
* }
* })
* ]);
*
* 2) Named visitors that trigger upon entering and leaving a node of
* a specific kind.
*
* visit(ast, {
* Kind: {
* enter(node) {
* Visitor::visit($ast, [
* 'Kind' => [
* 'enter' => function ($node) {
* // enter the "Kind" node
* }
* leave(node) {
* 'leave' => function ($node) {
* // leave the "Kind" node
* }
* }
* })
* ]
* ]);
*
* 3) Generic visitors that trigger upon entering and leaving any node.
*
* visit(ast, {
* enter(node) {
* Visitor::visit($ast, [
* 'enter' => function ($node) {
* // enter any node
* },
* leave(node) {
* 'leave' => function ($node) {
* // leave any node
* }
* })
* ]);
*
* 4) Parallel visitors for entering and leaving nodes of a specific kind.
*
* visit(ast, {
* enter: {
* Kind(node) {
* Visitor::visit($ast, [
* 'enter' => [
* 'Kind' => function($node) {
* // enter the "Kind" node
* }
* },
* leave: {
* Kind(node) {
* 'leave' => [
* 'Kind' => function ($node) {
* // leave the "Kind" node
* }
* }
* })
* ]
* ]);
*
* @param Node $root
* @param array $visitor
* @param array $keyMap
* @return Node|mixed
* @throws \Exception
*/
public static function visit($root, $visitor, $keyMap = null)
{

12
src/Type/Definition/ResolveInfo.php
View File

@ -34,12 +34,12 @@ class ResolveInfo
public $fieldNodes;
/**
* @var OutputType
* @var ScalarType|ObjectType|InterfaceType|UnionType|EnumType|ListOfType|NonNull
*/
public $returnType;
/**
* @var Type|CompositeType
* @var ObjectType|InterfaceType|UnionType
*/
public $parentType;
@ -80,10 +80,9 @@ class ResolveInfo
}
/**
* Helper method that returns names of all fields selected in query for $this->fieldName up to $depth levels
* Helper method that returns names of all fields selected in query for
* $this->fieldName up to $depth levels
*
*
* query AppHomeRoute{viewer{id,..._0c28183ce}} fragment _0c28183ce on Viewer{id,profile{firstName,id,locations{id}}}
* Example:
* query MyQuery{
* {
@ -98,7 +97,8 @@ class ResolveInfo
* }
* }
*
* Given this ResolveInfo instance is a part of "root" field resolution, and $depth === 1, method will return:
* Given this ResolveInfo instance is a part of "root" field resolution, and $depth === 1,
* method will return:
* [
* 'id' => true,
* 'nested' => [

8
src/Type/Schema.php
View File

@ -170,6 +170,8 @@ class Schema
* Returns array of all types in this schema. Keys of this array represent type names, values are instances
* of corresponding type definitions
*
* This operation requires full schema scan. Do not use in production environment.
*
* @return Type[]
*/
public function getTypeMap()
@ -244,6 +246,8 @@ class Schema
* Returns all possible concrete types for given abstract type
* (implementations for interfaces and members of union type for unions)
*
* This operation requires full schema scan. Do not use in production environment.
*
* @param AbstractType $abstractType
* @return ObjectType[]
*/
@ -359,6 +363,10 @@ class Schema
}
/**
* Validates schema.
*
* This operation requires full schema scan. Do not use in production environment.
*
* @throws InvariantViolation
*/
public function assertValid()

2
src/Type/SchemaConfig.php
View File

@ -45,6 +45,8 @@ class SchemaConfig
public $typeLoader;
/**
* Converts an array of options to instance of SchemaConfig
*
* @param array $options
* @return SchemaConfig
*/

47
src/Validator/DocumentValidator.php
View File

@ -1,6 +1,7 @@
<?php
namespace GraphQL\Validator;
use GraphQL\Error\Error;
use GraphQL\Error\InvariantViolation;
use GraphQL\Language\AST\ListValueNode;
use GraphQL\Language\AST\DocumentNode;
@ -54,6 +55,11 @@ class DocumentValidator
private static $initRules = false;
/**
* Returns all validation rules
*
* @return callable[]
*/
public static function allRules()
{
if (!self::$initRules) {
@ -104,6 +110,12 @@ class DocumentValidator
return self::$defaultRules;
}
/**
* Returns validation rule
*
* @param string $name
* @return callable|null
*/
public static function getRule($name)
{
$rules = static::allRules();
@ -111,12 +123,45 @@ class DocumentValidator
return isset($rules[$name]) ? $rules[$name] : null ;
}
/**
* Add rule to list of default validation rules
*
* @param string $name
* @param callable $rule
*/
public static function addRule($name, callable $rule)
{
self::$rules[$name] = $rule;
}
public static function validate(Schema $schema, DocumentNode $ast, array $rules = null, TypeInfo $typeInfo = null)
/**
* Implements the "Validation" section of the spec.
*
* Validation runs synchronously, returning an array of encountered errors, or
* an empty array if no errors were encountered and the document is valid.
*
* A list of specific validation rules may be provided. If not provided, the
* default list of rules defined by the GraphQL specification will be used.
*
* Each validation rules is a function which returns a visitor
* (see the GraphQL\Language\Visitor API). Visitor methods are expected to return
* GraphQL\Error\Error, or arrays of GraphQL\Error\Error when invalid.
*
* Optionally a custom TypeInfo instance may be provided. If not provided, one
* will be created from the provided schema.
*
* @param Schema $schema
* @param DocumentNode $ast
* @param array|null $rules
* @param TypeInfo|null $typeInfo
* @return Error[]
*/
public static function validate(
Schema $schema,
DocumentNode $ast,
array $rules = null,
TypeInfo $typeInfo = null
)
{
if (null === $rules) {
$rules = static::allRules();