Documentation etc.

src/Model.php

@@ -41,4 +41,35 @@ public function getShema();
      * @return Record A record.
      */
     public function create(array $data = array(), $allowedFields = null);
+
+    /**
+     * Make a selection that selects a single record.
+     * @param Record $record
+     *            A record.
+     * @return Query\AnySelectable A selection.
+     */
+    public function selectRecord(Record $record);
+
+    /**
+     * Make a selection that selects everything except for a single record.
+     *
+     * @param Record $record
+     *            A record.
+     * @return Query\AnySelectable A selection.
+     */
+    public function selectNotRecord(Record $record);
+
+    /**
+     * Find a record by its primary key. If the primary key
+     * consists of multiple fields, this function expects a
+     * parameter for each field (in alphabetical order).
+     * @param mixed $primary
+     *            Value of primary key.
+     * @param mixed ...$primary
+     *            For multifield primary key.
+     * @return Record|null A single matching record or null if it doesn't exist.
+     * @throws InvalidArgumentException If number of parameters does not
+     * match size of primary key.
+     */
+    public function find($primary);
 }

src/Query/AnySelectable.php

@@ -0,0 +1,13 @@
+<?php
+// Jivoo
+// Copyright (c) 2015 Niels Sonnich Poulsen (http://nielssp.dk)
+// Licensed under the MIT license.
+// See the LICENSE file or http://opensource.org/licenses/MIT for more information.
+namespace Jivoo\Data\Query;
+
+/**
+ * A record selection with a predicate, an ordering and a limit.
+ */
+interface AnySelectable extends Updatable, Readable, Deletable
+{
+}

src/Query/Boolean.php

@@ -8,8 +8,8 @@
 /**
  * An interface for combining expressions using boolean logic.
  *
- * @method Boolean and(Expression|string $expr, mixed $vars,... ) AND operator.
- * @method Boolean or(Expression|string $expr, mixed $vars,... ) OR operator.
+ * @method static and(Expression|string $expr, mixed $vars,... ) AND operator.
+ * @method static or(Expression|string $expr, mixed $vars,... ) OR operator.
  */
 interface Boolean
 {
@@ -21,7 +21,7 @@ interface Boolean
      *            Method name ('and' or 'or')
      * @param mixed[] $args
      *            List of parameters
-     * @return Boolean Expression.
+     * @return static
      */
     public function __call($method, $args);
 
@@ -33,7 +33,7 @@ public function __call($method, $args);
      * @param mixed $vars,...
      *            Additional values to replace placeholders in
      *            $expr with.
-     * @return Boolean Expression.
+     * @return static
      */
     public function where($expr);
 
@@ -45,7 +45,7 @@ public function where($expr);
      * @param mixed $vars,...
      *            Additional values to replace placeholders in
      *            $expr with.
-     * @return Boolean Expression.
+     * @return static
      */
     public function andWhere($expr);
 
@@ -57,7 +57,7 @@ public function andWhere($expr);
      * @param mixed $vars,...
      *            Additional values to replace placeholders in
      *            $expr with.
-     * @return Boolean Expression.
+     * @return static
      */
     public function orWhere($expr);
 }

src/Query/Builders/SelectionBuilder.php

@@ -7,11 +7,8 @@
 
 use Jivoo\Data\DataSource;
 use Jivoo\Data\DataType;
-use Jivoo\Data\Model;
-use Jivoo\Data\Query\Deletable;
-use Jivoo\Data\Query\Readable;
+use Jivoo\Data\Query\AnySelectable;
 use Jivoo\Data\Query\ReadSelection;
-use Jivoo\Data\Query\Updatable;
 use Jivoo\Data\Query\UpdateSelection;
 use Jivoo\Data\Record;
 use Jivoo\Data\Schema;
@@ -21,7 +18,7 @@
  * Will transform into a more specific selection based
  * on use.
  */
-class SelectionBuilder extends SelectionBase implements Readable, ReadSelection, Updatable, UpdateSelection, Deletable
+class SelectionBuilder extends SelectionBase implements AnySelectable, ReadSelection, UpdateSelection
 {
 
     /**
@@ -99,9 +96,9 @@ public function getData()
     /**
      * Copy attributes into a basic selection.
      *
-     * @param BasicSelectionBase $copy
+     * @param SelectionBase $copy
      *            A basic selection.
-     * @return BasicSelectionBase A basic selection.
+     * @return SelectionBase A basic selection.
      */
     private function copyBasicAttr(SelectionBase $copy)
     {

src/Query/Readable.php

@@ -20,7 +20,7 @@ interface Readable extends Selectable, \IteratorAggregate, \Countable
      *
      * @param int $offset
      *            Offset.
-     * @return Readable A readable selection.
+     * @return static
      */
     public function offset($offset);
 
@@ -29,7 +29,7 @@ public function offset($offset);
      *
      * @param string $alias
      *            Alias.
-     * @return Readable A readable selection.
+     * @return static
      */
     public function alias($alias);
 
@@ -49,26 +49,26 @@ public function select($expression, $alias = null);
     /**
      * Append an extra virtual field to the returned records.
      *
-     * @param string $alias
+     * @param string $field
      *            Name of new field.
      * @param Expression|string $expression
      *            Expression for field, e.g. 'COUNT(*)'.
      * @param DataType|null $type
      *            Optional type of field.
-     * @return ReadSelection A read selection.
+     * @return static
      */
     public function with($field, $expression, DataType $type = null);
 
     /**
      * Append an extra virtual field (with a record as the value) to the returned
      * records.
      *
-     * @param string $alias
+     * @param string $field
      *            Name of new field, expects the associated model to be
      *            aliased with the same name.
      * @param Schema $schema
      *            Schema of associated record.
-     * @return Readable A readable selection.
+     * @return static
      */
     public function withRecord($field, Schema $schema);
 
@@ -80,7 +80,7 @@ public function withRecord($field, Schema $schema);
      *            names.
      * @param Expression|string $predicate
      *            Grouping predicate.
-     * @return Readable A readable selection.
+     * @return static
      */
     public function groupBy($columns, $predicate = null);
 
@@ -93,7 +93,7 @@ public function groupBy($columns, $predicate = null);
      *            Join condition.
      * @param string $alias
      *            Alias for joined model/table.
-     * @return Readable A readable selection.
+     * @return static
      */
     public function innerJoin(DataSource $other, $condition, $alias = null);
 
@@ -106,7 +106,7 @@ public function innerJoin(DataSource $other, $condition, $alias = null);
      *            Join condition.
      * @param string $alias
      *            Alias for joined model/table.
-     * @return Readable A readable selection.
+     * @return static
      */
     public function leftJoin(DataSource $other, $condition, $alias = null);
 
@@ -119,7 +119,7 @@ public function leftJoin(DataSource $other, $condition, $alias = null);
      *            Join condition.
      * @param string $alias
      *            Alias for joined model/table.
-     * @return Readable A readable selection.
+     * @return static
      */
     public function rightJoin(DataSource $other, $condition, $alias = null);
 
@@ -129,7 +129,7 @@ public function rightJoin(DataSource $other, $condition, $alias = null);
      *
      * @param bool $distinct
      *            Whether to fetch only distinct records.
-     * @return Readable A readable selection.
+     * @return static
      */
     public function distinct($distinct = true);
 

src/Query/ReadableTrait.php

@@ -20,7 +20,7 @@ trait ReadableTrait
      *
      * @param int $offset
      *            Offset.
-     * @return Readable A readable selection.
+     * @return ReadSelectionBuilder A read selection.
      */
     public function offset($offset)
     {
@@ -33,7 +33,7 @@ public function offset($offset)
      *
      * @param string $alias
      *            Alias.
-     * @return Readable A readable selection.
+     * @return ReadSelectionBuilder A read selection.
      */
     public function alias($alias)
     {
@@ -44,12 +44,13 @@ public function alias($alias)
     /**
      * Make a projection.
      *
-     * @param string|string[]|array $expression
-     *            Expression or array of expressions
-     *            and aliases
+     * @param string|string[]|Expression|Expression[] $expression
+     *            Expression or array of expressions (if the keys are strings,
+     *            they are used as aliases).
      * @param string $alias
      *            Alias.
-     * @return array[] List of associative arrays
+     * @return \Iterator A {@see Record} iterator.
+     * @todo Rename to 'project' ?
      */
     public function select($expression, $alias = null)
     {
@@ -62,11 +63,11 @@ public function select($expression, $alias = null)
      *
      * @param string $alias
      *            Name of new field.
-     * @param string $expression
+     * @param Expression|string $expression
      *            Expression for field, e.g. 'COUNT(*)'.
      * @param DataType|null $type
      *            Optional type of field.
-     * @return ReadSelection A read selection.
+     * @return ReadSelectionBuilder A read selection.
      */
     public function with($field, $expression, DataType $type = null)
     {
@@ -78,12 +79,12 @@ public function with($field, $expression, DataType $type = null)
      * Append an extra virtual field (with a record as the value) to the returned
      * records.
      *
-     * @param string $alias
+     * @param string $field
      *            Name of new field, expects the associated model to be
      *            aliased with the same name.
      * @param Schema $schema
      *            Schema of associated record.
-     * @return Readable A readable selection.
+     * @return ReadSelectionBuilder A read selection.
      */
     public function withRecord($field, Schema $schema)
     {
@@ -99,7 +100,7 @@ public function withRecord($field, Schema $schema)
      *            names.
      * @param Expression|string $predicate
      *            Grouping predicate.
-     * @return Readable A readable selection.
+     * @return ReadSelectionBuilder A read selection.
      */
     public function groupBy($columns, $predicate = null)
     {
@@ -116,7 +117,7 @@ public function groupBy($columns, $predicate = null)
      *            Join condition.
      * @param string $alias
      *            Alias for joined model/table.
-     * @return Readable A readable selection.
+     * @return ReadSelectionBuilder A read selection.
      */
     public function innerJoin(DataSource $other, $condition, $alias = null)
     {
@@ -133,7 +134,7 @@ public function innerJoin(DataSource $other, $condition, $alias = null)
      *            Join condition.
      * @param string $alias
      *            Alias for joined model/table.
-     * @return Readable A readable selection.
+     * @return ReadSelectionBuilder A read selection.
      */
     public function leftJoin(DataSource $other, $condition, $alias = null)
     {
@@ -150,7 +151,7 @@ public function leftJoin(DataSource $other, $condition, $alias = null)
      *            Join condition.
      * @param string $alias
      *            Alias for joined model/table.
-     * @return Readable A readable selection.
+     * @return ReadSelectionBuilder A read selection.
      */
     public function rightJoin(DataSource $other, $condition, $alias = null)
     {
@@ -164,7 +165,7 @@ public function rightJoin(DataSource $other, $condition, $alias = null)
      *
      * @param bool $distinct
      *            Whether to fetch only distinct records.
-     * @return Readable A readable selection.
+     * @return ReadSelectionBuilder A read selection.
      */
     public function distinct($distinct = true)
     {

src/Query/Selectable.php

@@ -17,7 +17,7 @@ interface Selectable extends Boolean
      * @param Expression|string|null $expression
      *            Expression or column.
      *            If null all ordering will be removed from selection.
-     * @return Selectable A selection.
+     * @return static
      */
     public function orderBy($expr);
 
@@ -26,14 +26,14 @@ public function orderBy($expr);
      *
      * @param Expression|string $expression
      *            Expression or column.
-     * @return Selectable A selection.
+     * @return static
      */
     public function orderByDescending($expr);
 
     /**
      * Reverse the ordering.
      *
-     * @return Selectable A selection.
+     * @return static
      */
     public function reverseOrder();
 
@@ -42,7 +42,7 @@ public function reverseOrder();
      *
      * @param int $limit
      *            Number of records.
-     * @return Selectable A selection.
+     * @return static
      */
     public function limit($limit);
 }