Commit c542d09d by Paul Klimov

Doc comments at \yii\mongo\file\* updated.

parent c783e9fd
......@@ -11,7 +11,23 @@ use yii\db\ActiveQueryInterface;
use yii\db\ActiveQueryTrait;
/**
* Class ActiveQuery
* ActiveQuery represents a Mongo query associated with an file Active Record class.
*
* ActiveQuery instances are usually created by [[ActiveRecord::find()]].
*
* Because ActiveQuery extends from [[Query]], one can use query methods, such as [[where()]],
* [[orderBy()]] to customize the query options.
*
* ActiveQuery also provides the following additional query options:
*
* - [[with()]]: list of relations that this query should be performed with.
* - [[asArray()]]: whether to return each record as an array.
*
* These options can be configured using methods of the same name. For example:
*
* ~~~
* $images = ImageFile::find()->with('tags')->asArray()->all();
* ~~~
*
* @author Paul Klimov <klimov.paul@gmail.com>
* @since 2.0
......
......@@ -14,16 +14,47 @@ use yii\web\UploadedFile;
/**
* ActiveRecord is the base class for classes representing Mongo GridFS files in terms of objects.
*
* To specify source file use the [[file]] attribute. It can be specified in one of the following ways:
* - string - full name of the file, which content should be stored in GridFS
* - \yii\web\UploadedFile - uploaded file instance, which content should be stored in GridFS
*
* For example:
*
* ~~~
* $record = new ImageFile();
* $record->file = '/path/to/some/file.jpg';
* $record->save();
* ~~~
*
* You can also specify file content via [[newFileContent]] attribute:
*
* ~~~
* $record = new ImageFile();
* $record->newFileContent = 'New file content';
* $record->save();
* ~~~
*
* Note: [[newFileContent]] always takes precedence over [[file]].
*
* @property \MongoId|string $_id primary key.
* @property string $filename name of stored file.
* @property \MongoDate $uploadDate file upload date.
* @property integer $length file size.
* @property integer $chunkSize file chunk size.
* @property string $md5 file md5 hash.
* @property \MongoGridFSFile|\yii\web\UploadedFile|string $file associated file.
* @property string $newFileContent new file content.
*
* @author Paul Klimov <klimov.paul@gmail.com>
* @since 2.0
*/
class ActiveRecord extends \yii\mongo\ActiveRecord
abstract class ActiveRecord extends \yii\mongo\ActiveRecord
{
/**
* Creates an [[ActiveQuery]] instance.
* This method is called by [[find()]] to start a "find" command.
* You may override this method to return a customized query (e.g. `CustomerQuery` specified
* written for querying `Customer` purpose.)
* You may override this method to return a customized query (e.g. `ImageFileQuery` specified
* written for querying `ImageFile` purpose.)
* @return ActiveQuery the newly created [[ActiveQuery]] instance.
*/
public static function createQuery()
......@@ -55,7 +86,18 @@ class ActiveRecord extends \yii\mongo\ActiveRecord
/**
* Returns the list of all attribute names of the model.
* This method could be overridden by child classes to define available attributes.
* Note: primary key attribute "_id" should be always present in returned array.
* Note: all attributes defined in base Active Record class should be always present
* in returned array.
* For example:
* ~~~
* public function attributes()
* {
* return array_merge(
* parent::attributes(),
* ['tags', 'status']
* );
* }
* ~~~
* @return array list of attribute names.
*/
public function attributes()
......
......@@ -13,6 +13,10 @@ use Yii;
/**
* Collection represents the Mongo GridFS collection information.
*
* A file collection object is usually created by calling [[Database::getFileCollection()]] or [[Connection::getFileCollection()]].
*
* File collection inherits all interface from regular [[\yii\mongo\Collection]], adding methods to store files.
*
* @property \yii\mongo\Collection $chunkCollection file chunks Mongo collection. This property is read-only.
* @method \MongoGridFSCursor find() returns a cursor for the search results.
*
......@@ -61,6 +65,8 @@ class Collection extends \yii\mongo\Collection
}
/**
* Creates new file in GridFS collection from given local filesystem file.
* Additional attributes can be added file document using $metadata.
* @param string $filename name of the file to store.
* @param array $metadata other metadata fields to include in the file document.
* @param array $options list of options in format: optionName => optionValue
......@@ -85,6 +91,8 @@ class Collection extends \yii\mongo\Collection
}
/**
* Creates new file in GridFS collection with specified content.
* Additional attributes can be added file document using $metadata.
* @param string $bytes string of bytes to store.
* @param array $metadata other metadata fields to include in the file document.
* @param array $options list of options in format: optionName => optionValue
......@@ -109,6 +117,8 @@ class Collection extends \yii\mongo\Collection
}
/**
* Creates new file in GridFS collection from uploaded file.
* Additional attributes can be added file document using $metadata.
* @param string $name name of the uploaded file to store. This should correspond to
* the file field's name attribute in the HTML form.
* @param array $metadata other metadata fields to include in the file document.
......
......@@ -12,7 +12,11 @@ use yii\helpers\Json;
use yii\mongo\Exception;
/**
* Class Query
* Query represents Mongo "find" operation for GridFS collection.
*
* Query behaves exactly as regular [[\yii\mongo\Query]].
* Found files will be represented as arrays of file document attributes with
* additional 'file' key, which stores [[\MongoGridFSFile]] instance.
*
* @author Paul Klimov <klimov.paul@gmail.com>
* @since 2.0
......
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