Skip to content
This repository
Browse code

More API description/examples to relations variables.

  • Loading branch information...
commit 7581db2cf24c3ac0beb4107752774a0f6eadb6bb 1 parent 0fcf6f6
Juan Basso authored

Showing 1 changed file with 167 additions and 0 deletions. Show diff stats Hide diff stats

  1. 167  lib/Cake/Model/Model.php
167  lib/Cake/Model/Model.php
@@ -262,6 +262,45 @@ class Model extends Object {
262 262
 /**
263 263
  * Detailed list of belongsTo associations.
264 264
  *
  265
+ * ### Basic usage
  266
+ *
  267
+ * `public $belongsTo = array('Group', 'Department');`
  268
+ *
  269
+ * ### Detailed configuration
  270
+ *
  271
+ * {{{
  272
+ * public $belongsTo = array(
  273
+ *     'Group',
  274
+ *     'Department' => array(
  275
+ *         'className' => 'Department',
  276
+ *         'foreignKey' => 'department_id'
  277
+ *     )
  278
+ * );
  279
+ * }}}
  280
+ *
  281
+ * ### Possible keys in association
  282
+ *
  283
+ * - `className`: the classname of the model being associated to the current model.
  284
+ *   If you’re defining a ‘Profile belongsTo User’ relationship, the className key should equal ‘User.’
  285
+ * - `foreignKey`: the name of the foreign key found in the current model. This is
  286
+ *   especially handy if you need to define multiple belongsTo relationships. The default
  287
+ *   value for this key is the underscored, singular name of the other model, suffixed with ‘_id’.
  288
+ * - `conditions`: An SQL fragment used to filter related model records. It’s good
  289
+ *   practice to use model names in SQL fragments: “User.active = 1” is always
  290
+ *   better than just “active = 1.”
  291
+ * - `type`: the type of the join to use in the SQL query, default is LEFT which
  292
+ *   may not fit your needs in all situations, INNER may be helpful when you want
  293
+ *   everything from your main and associated models or nothing at all!(effective
  294
+ *   when used with some conditions of course). (NB: type value is in lower case - i.e. left, inner)
  295
+ * - `fields`: A list of fields to be retrieved when the associated model data is
  296
+ *   fetched. Returns all fields by default.
  297
+ * - `order`: An SQL fragment that defines the sorting order for the returned associated rows.
  298
+ * - `counterCache`: If set to true the associated Model will automatically increase or
  299
+ *   decrease the “[singular_model_name]_count” field in the foreign table whenever you do
  300
+ *   a save() or delete(). If its a string then its the field name to use. The value in the
  301
+ *   counter field represents the number of related rows.
  302
+ * - `counterScope`: Optional conditions array to use for updating counter cache field.
  303
+ *
265 304
  * @var array
266 305
  * @link http://book.cakephp.org/view/1042/belongsTo
267 306
  */
@@ -270,6 +309,41 @@ class Model extends Object {
270 309
 /**
271 310
  * Detailed list of hasOne associations.
272 311
  *
  312
+ * ### Basic usage
  313
+ *
  314
+ * `public $hasOne = array('Profile', 'Address');`
  315
+ *
  316
+ * ### Detailed configuration
  317
+ *
  318
+ * {{{
  319
+ * public $hasOne = array(
  320
+ *     'Profile',
  321
+ *     'Address' => array(
  322
+ *         'className' => 'Address',
  323
+ *         'foreignKey' => 'user_id'
  324
+ *     )
  325
+ * );
  326
+ * }}}
  327
+ *
  328
+ * ### Possible keys in association
  329
+ *
  330
+ * - `className`: the classname of the model being associated to the current model.
  331
+ *   If you’re defining a ‘User hasOne Profile’ relationship, the className key should equal ‘Profile.’
  332
+ * - `foreignKey`: the name of the foreign key found in the other model. This is
  333
+ *   especially handy if you need to define multiple hasOne relationships.
  334
+ *   The default value for this key is the underscored, singular name of the
  335
+ *   current model, suffixed with ‘_id’. In the example above it would default to 'user_id'.
  336
+ * - `conditions`: An SQL fragment used to filter related model records. It’s good
  337
+ *   practice to use model names in SQL fragments: “Profile.approved = 1” is
  338
+ *   always better than just “approved = 1.”
  339
+ * - `fields`: A list of fields to be retrieved when the associated model data is
  340
+ *   fetched. Returns all fields by default.
  341
+ * - `order`: An SQL fragment that defines the sorting order for the returned associated rows.
  342
+ * - `dependent`: When the dependent key is set to true, and the model’s delete()
  343
+ *   method is called with the cascade parameter set to true, associated model
  344
+ *   records are also deleted. In this case we set it true so that deleting a
  345
+ *   User will also delete her associated Profile.
  346
+ *
273 347
  * @var array
274 348
  * @link http://book.cakephp.org/view/1041/hasOne
275 349
  */
@@ -278,6 +352,47 @@ class Model extends Object {
278 352
 /**
279 353
  * Detailed list of hasMany associations.
280 354
  *
  355
+ * ### Basic usage
  356
+ *
  357
+ * `public $hasMany = array('Comment', 'Task');`
  358
+ *
  359
+ * ### Detailed configuration
  360
+ *
  361
+ * {{{
  362
+ * public $hasMany = array(
  363
+ *     'Comment',
  364
+ *     'Task' => array(
  365
+ *         'className' => 'Task',
  366
+ *         'foreignKey' => 'user_id'
  367
+ *     )
  368
+ * );
  369
+ * }}}
  370
+ *
  371
+ * ### Possible keys in association
  372
+ *
  373
+ * - `className`: the classname of the model being associated to the current model.
  374
+ *   If you’re defining a ‘User hasMany Comment’ relationship, the className key should equal ‘Comment.’
  375
+ * - `foreignKey`: the name of the foreign key found in the other model. This is
  376
+ *   especially handy if you need to define multiple hasMany relationships. The default
  377
+ *   value for this key is the underscored, singular name of the actual model, suffixed with ‘_id’.
  378
+ * - `conditions`: An SQL fragment used to filter related model records. It’s good
  379
+ *   practice to use model names in SQL fragments: “Comment.status = 1” is always
  380
+ *   better than just “status = 1.”
  381
+ * - `fields`: A list of fields to be retrieved when the associated model data is
  382
+ *   fetched. Returns all fields by default.
  383
+ * - `order`: An SQL fragment that defines the sorting order for the returned associated rows.
  384
+ * - `limit`: The maximum number of associated rows you want returned.
  385
+ * - `offset`: The number of associated rows to skip over (given the current
  386
+ *   conditions and order) before fetching and associating.
  387
+ * - `dependent`: When dependent is set to true, recursive model deletion is
  388
+ *   possible. In this example, Comment records will be deleted when their
  389
+ *   associated User record has been deleted.
  390
+ * - `exclusive`: When exclusive is set to true, recursive model deletion does
  391
+ *   the delete with a deleteAll() call, instead of deleting each entity separately.
  392
+ *   This greatly improves performance, but may not be ideal for all circumstances.
  393
+ * - `finderQuery`: A complete SQL query CakePHP can use to fetch associated model
  394
+ *   records. This should be used in situations that require very custom results.
  395
+ *
281 396
  * @var array
282 397
  * @link http://book.cakephp.org/view/1043/hasMany
283 398
  */
@@ -286,6 +401,58 @@ class Model extends Object {
286 401
 /**
287 402
  * Detailed list of hasAndBelongsToMany associations.
288 403
  *
  404
+ * ### Basic usage
  405
+ *
  406
+ * `public $hasAndBelongsToMany = array('Role', 'Address');`
  407
+ *
  408
+ * ### Detailed configuration
  409
+ *
  410
+ * {{{
  411
+ * public $hasAndBelongsToMany = array(
  412
+ *     'Role',
  413
+ *     'Address' => array(
  414
+ *         'className' => 'Address',
  415
+ *         'foreignKey' => 'user_id',
  416
+ *         'associationForeignKey' => 'address_id',
  417
+ *         'joinTable' => 'addresses_users'
  418
+ *     )
  419
+ * );
  420
+ * }}}
  421
+ *
  422
+ * ### Possible keys in association
  423
+ *
  424
+ * - `className`: the classname of the model being associated to the current model.
  425
+ *   If you're defining a ‘Recipe HABTM Tag' relationship, the className key should equal ‘Tag.'
  426
+ * - `joinTable`: The name of the join table used in this association (if the
  427
+ *   current table doesn't adhere to the naming convention for HABTM join tables).
  428
+ * - `with`: Defines the name of the model for the join table. By default CakePHP
  429
+ *   will auto-create a model for you. Using the example above it would be called
  430
+ *   RecipesTag. By using this key you can override this default name. The join
  431
+ *   table model can be used just like any "regular" model to access the join table directly.
  432
+ * - `foreignKey`: the name of the foreign key found in the current model.
  433
+ *   This is especially handy if you need to define multiple HABTM relationships.
  434
+ *   The default value for this key is the underscored, singular name of the
  435
+ *   current model, suffixed with ‘_id'.
  436
+ * - `associationForeignKey`: the name of the foreign key found in the other model.
  437
+ *   This is especially handy if you need to define multiple HABTM relationships.
  438
+ *   The default value for this key is the underscored, singular name of the other
  439
+ *   model, suffixed with ‘_id'.
  440
+ * - `unique`: If true (default value) cake will first delete existing relationship
  441
+ *   records in the foreign keys table before inserting new ones, when updating a
  442
+ *   record. So existing associations need to be passed again when updating.
  443
+ * - `conditions`: An SQL fragment used to filter related model records. It's good
  444
+ *   practice to use model names in SQL fragments: "Comment.status = 1" is always
  445
+ *   better than just "status = 1."
  446
+ * - `fields`: A list of fields to be retrieved when the associated model data is
  447
+ *   fetched. Returns all fields by default.
  448
+ * - `order`: An SQL fragment that defines the sorting order for the returned associated rows.
  449
+ * - `limit`: The maximum number of associated rows you want returned.
  450
+ * - `offset`: The number of associated rows to skip over (given the current
  451
+ *   conditions and order) before fetching and associating.
  452
+ * - `finderQuery`, `deleteQuery`, `insertQuery`: A complete SQL query CakePHP
  453
+ *   can use to fetch, delete, or create new associated model records. This should
  454
+ *   be used in situations that require very custom results.
  455
+ *
289 456
  * @var array
290 457
  * @link http://book.cakephp.org/view/1044/hasAndBelongsToMany-HABTM
291 458
  */

0 notes on commit 7581db2

Please sign in to comment.
Something went wrong with that request. Please try again.