Skip to content

Y
yii2
Commit 8f491f28 by Carsten Brandt
Options

moved `@include` tags of api docs directly into the class

parent 0d720e06
Showing with 164 additions and 173 deletions
docs/api/base/Component.md deleted 100644 → 0
Component is the base class that implements the *property*, *event* and *behavior* features.
Component provides the *event* and *behavior* features, in addition to the *property* feature which is implemented in
its parent class [[Object]].
Event is a way to "inject" custom code into existing code at certain places. For example, a comment object can trigger
an "add" event when the user adds a comment. We can write custom code and attach it to this event so that when the event
is triggered (i.e. comment will be added), our custom code will be executed.
An event is identified by a name that should be unique within the class it is defined at. Event names are *case-sensitive*.
One or multiple PHP callbacks, called *event handlers*, can be attached to an event. You can call [[trigger()]] to
raise an event. When an event is raised, the event handlers will be invoked automatically in the order they were
attached.
To attach an event handler to an event, call [[on()]]:
~~~
$post->on('update', function($event) {
// send email notification
});
~~~
In the above, an anonymous function is attached to the "update" event of the post. You may attach
the following types of event handlers:
- anonymous function: `function($event) { ... }`
- object method: `[$object, 'handleAdd']`
- static class method: `['Page', 'handleAdd']`
- global function: `'handleAdd'`
The signature of an event handler should be like the following:
~~~
function foo($event)
~~~
where `$event` is an [[Event]] object which includes parameters associated with the event.
You can also attach a handler to an event when configuring a component with a configuration array.
The syntax is like the following:
~~~
[
'on add' => function($event) { ... }
]
~~~
where `on add` stands for attaching an event to the `add` event.
Sometimes, you may want to associate extra data with an event handler when you attach it to an event
and then access it when the handler is invoked. You may do so by
~~~
$post->on('update', function($event) {
// the data can be accessed via $event->data
}, $data);
~~~
A behavior is an instance of [[Behavior]] or its child class. A component can be attached with one or multiple
behaviors. When a behavior is attached to a component, its public properties and methods can be accessed via the
component directly, as if the component owns those properties and methods.
To attach a behavior to a component, declare it in [[behaviors()]], or explicitly call [[attachBehavior]]. Behaviors
declared in [[behaviors()]] are automatically attached to the corresponding component.
One can also attach a behavior to a component when configuring it with a configuration array. The syntax is like the
following:
~~~
[
'as tree' => [
'class' => 'Tree',
],
]
~~~
where `as tree` stands for attaching a behavior named `tree`, and the array will be passed to [[\Yii::createObject()]]
to create the behavior object.
\ No newline at end of file
docs/api/base/Object.md deleted 100644 → 0
Object is the base class that implements the *property* feature.
A property is defined by a getter method (e.g. `getLabel`), and/or a setter method (e.g. `setLabel`). For example,
the following getter and setter methods define a property named `label`:
~~~
private $_label;
public function getLabel()
{
return $this->_label;
}
public function setLabel($value)
{
$this->_label = $value;
}
~~~
Property names are *case-insensitive*.
A property can be accessed like a member variable of an object. Reading or writing a property will cause the invocation
of the corresponding getter or setter method. For example,
~~~
// equivalent to $label = $object->getLabel();
$label = $object->label;
// equivalent to $object->setLabel('abc');
$object->label = 'abc';
~~~
If a property has only a getter method and has no setter method, it is considered as *read-only*. In this case, trying
to modify the property value will cause an exception.
One can call [[hasProperty()]], [[canGetProperty()]] and/or [[canSetProperty()]] to check the existence of a property.
Besides the property feature, Object also introduces an important object initialization life cycle. In particular,
creating an new instance of Object or its derived class will involve the following life cycles sequentially:
1. the class constructor is invoked;
2. object properties are initialized according to the given configuration;
3. the `init()` method is invoked.
In the above, both Step 2 and 3 occur at the end of the class constructor. It is recommended that
you perform object initialization in the `init()` method because at that stage, the object configuration
is already applied.
In order to ensure the above life cycles, if a child class of Object needs to override the constructor,
it should be done like the following:
~~~
public function __construct($param1, $param2, ..., $config = [])
{
...
parent::__construct($config);
}
~~~
That is, a `$config` parameter (defaults to `[]`) should be declared as the last parameter
of the constructor, and the parent implementation should be called at the end of the constructor.
docs/api/db/ActiveRecord-find.md deleted 100644 → 0
The returned [[ActiveQuery]] instance can be further customized by calling
methods defined in [[ActiveQuery]] before `one()`, `all()` or `value()` is
called to return the populated active records:
~~~
// find all customers
$customers = Customer::find()->all();
// find all active customers and order them by their age:
$customers = Customer::find()
->where(['status' => 1])
->orderBy('age')
->all();
// find a single customer whose primary key value is 10
$customer = Customer::find(10);
// the above is equivalent to:
$customer = Customer::find()->where(['id' => 10])->one();
// find a single customer whose age is 30 and whose status is 1
$customer = Customer::find(['age' => 30, 'status' => 1]);
// the above is equivalent to:
$customer = Customer::find()->where(['age' => 30, 'status' => 1])->one();
~~~
\ No newline at end of file
extensions/apidoc/templates/html/views/propertyDetails.php
......@@ -24,9 +24,9 @@ ArrayHelper::multisort($properties, 'name');
<?php echo $property->name; ?>
<span class="detailHeaderTag small">
<?= $property->visibility ?>
property
<?php if($property->getIsReadOnly()) echo ' <em>read-only</em> '; ?>
<?php if($property->getIsWriteOnly()) echo ' <em>write-only</em> '; ?>
property
<?php if(!empty($property->since)): ?>
(available since version <?php echo $property->since; ?>)
<?php endif; ?>
......
framework/base/Component.php
......@@ -12,7 +12,84 @@ use Yii;
/**
* Component is the base class that implements the *property*, *event* and *behavior* features.
*
* @include @yii/base/Component.md
* Component provides the *event* and *behavior* features, in addition to the *property* feature which is implemented in
* its parent class [[Object]].
*
* Event is a way to "inject" custom code into existing code at certain places. For example, a comment object can trigger
* an "add" event when the user adds a comment. We can write custom code and attach it to this event so that when the event
* is triggered (i.e. comment will be added), our custom code will be executed.
*
* An event is identified by a name that should be unique within the class it is defined at. Event names are *case-sensitive*.
*
* One or multiple PHP callbacks, called *event handlers*, can be attached to an event. You can call [[trigger()]] to
* raise an event. When an event is raised, the event handlers will be invoked automatically in the order they were
* attached.
*
* To attach an event handler to an event, call [[on()]]:
*
* ~~~
* $post->on('update', function($event) {
* // send email notification
* });
* ~~~
*
* In the above, an anonymous function is attached to the "update" event of the post. You may attach
* the following types of event handlers:
*
* - anonymous function: `function($event) { ... }`
* - object method: `[$object, 'handleAdd']`
* - static class method: `['Page', 'handleAdd']`
* - global function: `'handleAdd'`
*
* The signature of an event handler should be like the following:
*
* ~~~
* function foo($event)
* ~~~
*
* where `$event` is an [[Event]] object which includes parameters associated with the event.
*
* You can also attach a handler to an event when configuring a component with a configuration array.
* The syntax is like the following:
*
* ~~~
* [
* 'on add' => function($event) { ... }
* ]
* ~~~
*
* where `on add` stands for attaching an event to the `add` event.
*
* Sometimes, you may want to associate extra data with an event handler when you attach it to an event
* and then access it when the handler is invoked. You may do so by
*
* ~~~
* $post->on('update', function($event) {
* // the data can be accessed via $event->data
* }, $data);
* ~~~
*
*
* A behavior is an instance of [[Behavior]] or its child class. A component can be attached with one or multiple
* behaviors. When a behavior is attached to a component, its public properties and methods can be accessed via the
* component directly, as if the component owns those properties and methods.
*
* To attach a behavior to a component, declare it in [[behaviors()]], or explicitly call [[attachBehavior]]. Behaviors
* declared in [[behaviors()]] are automatically attached to the corresponding component.
*
* One can also attach a behavior to a component when configuring it with a configuration array. The syntax is like the
* following:
*
* ~~~
* [
* 'as tree' => [
* 'class' => 'Tree',
* ],
* ]
* ~~~
*
* where `as tree` stands for attaching a behavior named `tree`, and the array will be passed to [[\Yii::createObject()]]
* to create the behavior object.
*
* @property Behavior[] $behaviors List of behaviors attached to this component. This property is read-only.
*
......
framework/base/Object.php
......@@ -12,7 +12,65 @@ use Yii;
/**
* Object is the base class that implements the *property* feature.
*
* @include @yii/base/Object.md
* A property is defined by a getter method (e.g. `getLabel`), and/or a setter method (e.g. `setLabel`). For example,
* the following getter and setter methods define a property named `label`:
*
* ~~~
* private $_label;
*
* public function getLabel()
* {
* return $this->_label;
* }
*
* public function setLabel($value)
* {
* $this->_label = $value;
* }
* ~~~
*
* Property names are *case-insensitive*.
*
* A property can be accessed like a member variable of an object. Reading or writing a property will cause the invocation
* of the corresponding getter or setter method. For example,
*
* ~~~
* // equivalent to $label = $object->getLabel();
* $label = $object->label;
* // equivalent to $object->setLabel('abc');
* $object->label = 'abc';
* ~~~
*
* If a property has only a getter method and has no setter method, it is considered as *read-only*. In this case, trying
* to modify the property value will cause an exception.
*
* One can call [[hasProperty()]], [[canGetProperty()]] and/or [[canSetProperty()]] to check the existence of a property.
*
*
* Besides the property feature, Object also introduces an important object initialization life cycle. In particular,
* creating an new instance of Object or its derived class will involve the following life cycles sequentially:
*
* 1. the class constructor is invoked;
* 2. object properties are initialized according to the given configuration;
* 3. the `init()` method is invoked.
*
* In the above, both Step 2 and 3 occur at the end of the class constructor. It is recommended that
* you perform object initialization in the `init()` method because at that stage, the object configuration
* is already applied.
*
* In order to ensure the above life cycles, if a child class of Object needs to override the constructor,
* it should be done like the following:
*
* ~~~
* public function __construct($param1, $param2, ..., $config = [])
* {
* ...
* parent::__construct($config);
* }
* ~~~
*
* That is, a `$config` parameter (defaults to `[]`) should be declared as the last parameter
* of the constructor, and the parent implementation should be called at the end of the constructor.
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @since 2.0
......
framework/db/BaseActiveRecord.php
......@@ -93,7 +93,32 @@ abstract class BaseActiveRecord extends Model implements ActiveRecordInterface
/**
* Creates an [[ActiveQuery]] instance for query purpose.
*
* @include @yii/db/ActiveRecord-find.md
* The returned [[ActiveQuery]] instance can be further customized by calling
* methods defined in [[ActiveQuery]] before `one()`, `all()` or `value()` is
* called to return the populated active records:
*
* ~~~
* // find all customers
* $customers = Customer::find()->all();
*
* // find all active customers and order them by their age:
* $customers = Customer::find()
* ->where(['status' => 1])
* ->orderBy('age')
* ->all();
*
* // find a single customer whose primary key value is 10
* $customer = Customer::find(10);
*
* // the above is equivalent to:
* $customer = Customer::find()->where(['id' => 10])->one();
*
* // find a single customer whose age is 30 and whose status is 1
* $customer = Customer::find(['age' => 30, 'status' => 1]);
*
* // the above is equivalent to:
* $customer = Customer::find()->where(['age' => 30, 'status' => 1])->one();
* ~~~
*
* @param mixed $q the query parameter. This can be one of the followings:
*
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment