ExplicitElementTrait::findOne()

Completed

Push — develop ( d42524...0c0f5e )

by Nate

created 2019-01-10 21:36 UTC

↳ Parent: ExplicitElementTrait

Size

Total Lines

Duplication

Lines	0
Ratio	0 %

Importance

Changes

Metric	Value
dl	0
loc	1
ccs	0
cts	0
cp	0
c	0
b	0
f	0
nc	1

<?php

/**
 * @copyright  Copyright (c) Flipbox Digital Limited
 * @license    https://github.com/flipboxfactory/craft-ember/blob/master/LICENSE
 * @link       https://github.com/flipboxfactory/craft-ember/
 */

namespace flipbox\craft\ember\elements;

use craft\errors\ElementNotFoundException;
use craft\helpers\Json;

/**
 * @author Flipbox Factory <[email protected]>
 * @since 2.0.0
 */
trait ExplicitElementTrait
{
    /**
     * Returns a single element instance by a primary key or a set of element criteria parameters.
     *
     * The method accepts:
     *
     *  - an int: query by a single ID value and return the corresponding element (or null if not found).
     *  - an array of name-value pairs: query by a set of parameter values and return the first element
     *    matching all of them (or null if not found).
     *
     * Note that this method will automatically call the `one()` method and return an
     * [[ElementInterface|\craft\base\Element]] instance. For example,
     *
     * ```php
     * // find a single entry whose ID is 10
     * $entry = Entry::findOne(10);
     * // the above code is equivalent to:
     * $entry = Entry::find->id(10)->one();
     * // find the first user whose email ends in "example.com"
     * $user = User::findOne(['email' => '*example.com']);
     * // the above code is equivalent to:
     * $user = User::find()->email('*example.com')->one();
     * ```
     *
     * @param mixed $criteria The element ID or a set of element criteria parameters
     * @return static|null Element instance matching the condition, or null if nothing matches.
     */
    abstract public static function findOne($criteria);

    /**
     * Returns a list of elements that match the specified ID(s) or a set of element criteria parameters.
     *
     * The method accepts:
     *
     *  - an int: query by a single ID value and return an array containing the corresponding element
     *    (or an empty array if not found).
     *  - an array of integers: query by a list of ID values and return the corresponding elements (or an
     *    empty array if none was found).
     *    Note that an empty array will result in an empty result as it will be interpreted as a search for
     *    primary keys and not an empty set of element criteria parameters.
     *  - an array of name-value pairs: query by a set of parameter values and return an array of elements
     *    matching all of them (or an empty array if none was found).
     *
     * Note that this method will automatically call the `all()` method and return an array of
     * [[ElementInterface|\craft\base\Element]] instances. For example,
     *
     * ```php
     * // find the entries whose ID is 10
     * $entries = Entry::findAll(10);
     * // the above code is equivalent to:
     * $entries = Entry::find()->id(10)->all();
     * // find the entries whose ID is 10, 11 or 12.
     * $entries = Entry::findAll([10, 11, 12]);
     * // the above code is equivalent to:
     * $entries = Entry::find()->id([10, 11, 12]])->all();
     * // find users whose email ends in "example.com"
     * $users = User::findAll(['email' => '*example.com']);
     * // the above code is equivalent to:
     * $users = User::find()->email('*example.com')->all();
     * ```
     *
     * @param mixed $criteria The element ID, an array of IDs, or a set of element criteria parameters
     * @return static[] an array of Element instances, or an empty array if nothing matches.
     */
    abstract public static function findAll($criteria = null): array;

    /**
     * Returns a single element instance by a primary key or a set of element criteria parameters.
     *
     * The method accepts:
     *
     *  - an int: query by a single ID value and return the corresponding element (or null if not found).
     *  - an array of name-value pairs: query by a set of parameter values and return the first element
     *    matching all of them (or null if not found).
     *
     * Note that this method will automatically call the `one()` method and return an
     * [[ElementInterface|\craft\base\Element]] instance. For example,
     *
     * ```php
     * // find a single entry whose ID is 10
     * $entry = Entry::findOne(10);
     * // the above code is equivalent to:
     * $entry = Entry::find->id(10)->one();
     * // find the first user whose email ends in "example.com"
     * $user = User::findOne(['email' => '*example.com']);
     * // the above code is equivalent to:
     * $user = User::find()->email('*example.com')->one();
     * ```
     *
     * @param mixed $criteria The element ID or a set of element criteria parameters
     * @return static Element instance matching the condition, or null if nothing matches.
     * @throws ElementNotFoundException
     */
    public static function getOne($criteria)
    {
        if (null === ($element = static::findOne($criteria))) {
            throw new ElementNotFoundException(
                sprintf(
                    "Organization not found with the following criteria: %s",
                    Json::encode($criteria)
                )
            );
        }

        return $element;
    }

    /**
     * Returns a list of elements that match the specified ID(s) or a set of element criteria parameters.
     *
     * The method accepts:
     *
     *  - an int: query by a single ID value and return an array containing the corresponding element
     *    (or an empty array if not found).
     *  - an array of integers: query by a list of ID values and return the corresponding elements (or an
     *    empty array if none was found).
     *    Note that an empty array will result in an empty result as it will be interpreted as a search for
     *    primary keys and not an empty set of element criteria parameters.
     *  - an array of name-value pairs: query by a set of parameter values and return an array of elements
     *    matching all of them (or an empty array if none was found).
     *
     * Note that this method will automatically call the `all()` method and return an array of
     * [[ElementInterface|\craft\base\Element]] instances. For example,
     *
     * ```php
     * // find the entries whose ID is 10
     * $entries = Entry::findAll(10);
     * // the above code is equivalent to:
     * $entries = Entry::find()->id(10)->all();
     * // find the entries whose ID is 10, 11 or 12.
     * $entries = Entry::findAll([10, 11, 12]);
     * // the above code is equivalent to:
     * $entries = Entry::find()->id([10, 11, 12]])->all();
     * // find users whose email ends in "example.com"
     * $users = User::findAll(['email' => '*example.com']);
     * // the above code is equivalent to:
     * $users = User::find()->email('*example.com')->all();
     * ```
     *
     * @param mixed $criteria The element ID, an array of IDs, or a set of element criteria parameters
     * @return static[] an array of Element instances, or an empty array if nothing matches.
     * @throws ElementNotFoundException
     */
    public static function getAll($criteria)
    {
        $elements = static::findAll($criteria);

        if (empty($elements)) {
            throw new ElementNotFoundException(
                sprintf(
                    "Organization not found with the following criteria: %s",
                    Json::encode($criteria)
                )
            );
        }

        return $elements;
    }
}


1			<?php
2
3			/**
4			* @copyright Copyright (c) Flipbox Digital Limited
5			* @license https://github.com/flipboxfactory/craft-ember/blob/master/LICENSE
6			* @link https://github.com/flipboxfactory/craft-ember/
7			*/
8
9			namespace flipbox\craft\ember\elements;
10
11			use craft\errors\ElementNotFoundException;
12			use craft\helpers\Json;
13
14			/**
15			* @author Flipbox Factory <[email protected]>
16			* @since 2.0.0
17			*/
18			trait ExplicitElementTrait
19			{
20			/**
21			* Returns a single element instance by a primary key or a set of element criteria parameters.
22			*
23			* The method accepts:
24			*
25			* - an int: query by a single ID value and return the corresponding element (or null if not found).
26			* - an array of name-value pairs: query by a set of parameter values and return the first element
27			* matching all of them (or null if not found).
28			*
29			* Note that this method will automatically call the `one()` method and return an
30			* [[ElementInterface\|\craft\base\Element]] instance. For example,
31			*
32			* ```php
33			* // find a single entry whose ID is 10
34			* $entry = Entry::findOne(10);
35			* // the above code is equivalent to:
36			* $entry = Entry::find->id(10)->one();
37			* // find the first user whose email ends in "example.com"
38			* $user = User::findOne(['email' => '*example.com']);
39			* // the above code is equivalent to:
40			* $user = User::find()->email('*example.com')->one();
41			* ```
42			*
43			* @param mixed $criteria The element ID or a set of element criteria parameters
44			* @return static\|null Element instance matching the condition, or null if nothing matches.
45			*/
46			abstract public static function findOne($criteria);
47
48			/**
49			* Returns a list of elements that match the specified ID(s) or a set of element criteria parameters.
50			*
51			* The method accepts:
52			*
53			* - an int: query by a single ID value and return an array containing the corresponding element
54			* (or an empty array if not found).
55			* - an array of integers: query by a list of ID values and return the corresponding elements (or an
56			* empty array if none was found).
57			* Note that an empty array will result in an empty result as it will be interpreted as a search for
58			* primary keys and not an empty set of element criteria parameters.
59			* - an array of name-value pairs: query by a set of parameter values and return an array of elements
60			* matching all of them (or an empty array if none was found).
61			*
62			* Note that this method will automatically call the `all()` method and return an array of
63			* [[ElementInterface\|\craft\base\Element]] instances. For example,
64			*
65			* ```php
66			* // find the entries whose ID is 10
67			* $entries = Entry::findAll(10);
68			* // the above code is equivalent to:
69			* $entries = Entry::find()->id(10)->all();
70			* // find the entries whose ID is 10, 11 or 12.
71			* $entries = Entry::findAll([10, 11, 12]);
72			* // the above code is equivalent to:
73			* $entries = Entry::find()->id([10, 11, 12]])->all();
74			* // find users whose email ends in "example.com"
75			* $users = User::findAll(['email' => '*example.com']);
76			* // the above code is equivalent to:
77			* $users = User::find()->email('*example.com')->all();
78			* ```
79			*
80			* @param mixed $criteria The element ID, an array of IDs, or a set of element criteria parameters
81			* @return static[] an array of Element instances, or an empty array if nothing matches.
82			*/
83			abstract public static function findAll($criteria = null): array;
84
85			/**
86			* Returns a single element instance by a primary key or a set of element criteria parameters.
87			*
88			* The method accepts:
89			*
90			* - an int: query by a single ID value and return the corresponding element (or null if not found).
91			* - an array of name-value pairs: query by a set of parameter values and return the first element
92			* matching all of them (or null if not found).
93			*
94			* Note that this method will automatically call the `one()` method and return an
95			* [[ElementInterface\|\craft\base\Element]] instance. For example,
96			*
97			* ```php
98			* // find a single entry whose ID is 10
99			* $entry = Entry::findOne(10);
100			* // the above code is equivalent to:
101			* $entry = Entry::find->id(10)->one();
102			* // find the first user whose email ends in "example.com"
103			* $user = User::findOne(['email' => '*example.com']);
104			* // the above code is equivalent to:
105			* $user = User::find()->email('*example.com')->one();
106			* ```
107			*
108			* @param mixed $criteria The element ID or a set of element criteria parameters
109			* @return static Element instance matching the condition, or null if nothing matches.
110			* @throws ElementNotFoundException
111			*/
112			public static function getOne($criteria)
113			{
114			if (null === ($element = static::findOne($criteria))) {
115			throw new ElementNotFoundException(
116			sprintf(
117			"Organization not found with the following criteria: %s",
118			Json::encode($criteria)
119			)
120			);
121			}
122
123			return $element;
124			}
125
126			/**
127			* Returns a list of elements that match the specified ID(s) or a set of element criteria parameters.
128			*
129			* The method accepts:
130			*
131			* - an int: query by a single ID value and return an array containing the corresponding element
132			* (or an empty array if not found).
133			* - an array of integers: query by a list of ID values and return the corresponding elements (or an
134			* empty array if none was found).
135			* Note that an empty array will result in an empty result as it will be interpreted as a search for
136			* primary keys and not an empty set of element criteria parameters.
137			* - an array of name-value pairs: query by a set of parameter values and return an array of elements
138			* matching all of them (or an empty array if none was found).
139			*
140			* Note that this method will automatically call the `all()` method and return an array of
141			* [[ElementInterface\|\craft\base\Element]] instances. For example,
142			*
143			* ```php
144			* // find the entries whose ID is 10
145			* $entries = Entry::findAll(10);
146			* // the above code is equivalent to:
147			* $entries = Entry::find()->id(10)->all();
148			* // find the entries whose ID is 10, 11 or 12.
149			* $entries = Entry::findAll([10, 11, 12]);
150			* // the above code is equivalent to:
151			* $entries = Entry::find()->id([10, 11, 12]])->all();
152			* // find users whose email ends in "example.com"
153			* $users = User::findAll(['email' => '*example.com']);
154			* // the above code is equivalent to:
155			* $users = User::find()->email('*example.com')->all();
156			* ```
157			*
158			* @param mixed $criteria The element ID, an array of IDs, or a set of element criteria parameters
159			* @return static[] an array of Element instances, or an empty array if nothing matches.
160			* @throws ElementNotFoundException
161			*/
162			public static function getAll($criteria)
163			{
164			$elements = static::findAll($criteria);
165
166			if (empty($elements)) {
167			throw new ElementNotFoundException(
168			sprintf(
169			"Organization not found with the following criteria: %s",
170			Json::encode($criteria)
171			)
172			);
173			}
174
175			return $elements;
176			}
177			}
178

flipboxfactory / craft-ember

Push — develop ( d42524...0c0f5e )

ExplicitElementTrait::findOne()

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like