      1: <?php
      2:
      3: /*
      4:  * This file is part of the CRUDlex package.
      5:  *
      6:  * (c) Philip Lehmann-Böhm <philip@philiplb.de>
      7:  *
      8:  * For the full copyright and license information, please view the LICENSE
      9:  * file that was distributed with this source code.
     10:  */
     11:
     12: namespace CRUDlex;
     13:
     14: use Symfony\Component\HttpFoundation\Request;
     15: use Symfony\Component\HttpFoundation\Response;
     16:
     17: use CRUDlex\CRUDEntityDefinition;
     18: use CRUDlex\CRUDEntity;
     19:
     20: /**
     21:  * The abstract class for reading and writing data.
     22:  */
     23: abstract class CRUDData {
     24:
     25:     /**
     26:      * Holds the {@see CRUDEntityDefinition} entity definition.
     27:      */
     28:     protected $definition;
     29:
     30:     /**
     31:      * Holds the {@see CRUDFileProcessorInterface} file processor.
     32:      */
     33:     protected $fileProcessor;
     34:
     35:     /**
     36:      * Creates an {@see CRUDEntity} from the raw data array with the field name
     37:      * as keys and field values as values.
     38:      *
     39:      * @param array $row
     40:      * the array with the raw data
     41:      *
     42:      * @return CRUDEntity
     43:      * the entity containing the array data then
     44:      */
     45:     protected function hydrate(array $row) {
     46:         $fieldNames = $this->definition->getFieldNames();
     47:         $entity = new CRUDEntity($this->definition);
     48:         foreach ($fieldNames as $fieldName) {
     49:             $entity->set($fieldName, $row[$fieldName]);
     50:         }
     51:         return $entity;
     52:     }
     53:
     54:     /**
     55:      * Gets the entity with the given id.
     56:      *
     57:      * @param string $id
     58:      * the id
     59:      *
     60:      * @return CRUDEntity
     61:      * the entity belonging to the id or null if not existant
     62:      */
     63:     public abstract function get($id);
     64:
     65:
     66:     /**
     67:      * Gets a list of entities fullfilling the given filter or all if no
     68:      * selection was given.
     69:      *
     70:      * @param array $filter
     71:      * the filter all resulting entities must fulfill, the keys as field names
     72:      *
     73:      * @return array
     74:      * the entities fulfilling the filter or all if no filter was given
     75:      */
     76:     public abstract function listEntries(array $filter = array());
     77:
     78:     /**
     79:      * Persists the given entity as new entry in the datasource.
     80:      *
     81:      * @param CRUDEntity $entity
     82:      * the entity to persist.
     83:      */
     84:     public abstract function create(CRUDEntity $entity);
     85:
     86:     /**
     87:      * Updates an existing entry in the datasource having the same id.
     88:      *
     89:      * @param CRUDEntity $entity
     90:      * the entity with the new data
     91:      */
     92:     public abstract function update(CRUDEntity $entity);
     93:
     94:     /**
     95:      * Deletes an entry from the datasource having the given id.
     96:      *
     97:      * @param string $id
     98:      * the id of the entry to delete
     99:      */
    100:     public abstract function delete($id);
    101:
    102:     /**
    103:      * Gets ids and names of a table. Used for building up the dropdown box of
    104:      * reference type fields.
    105:      *
    106:      * @param string $table
    107:      * the table
    108:      * @param string nameField
    109:      * the field defining the name of the rows
    110:      *
    111:      * @return array
    112:      * an array with the ids as key and the names as values
    113:      */
    114:     public abstract function getReferences($table, $nameField);
    115:
    116:     /**
    117:      * Retrieves the amount of entities in the datasource fulfilling the given
    118:      * parameters.
    119:      *
    120:      * @param string $table
    121:      * the table to count in
    122:      * @param array $params
    123:      * an array with the field names as keys and field values as values
    124:      * @param array $paramOperators
    125:      * the operators of the parameters like "=" defining the full condition of the field
    126:      * @param bool $includeDeleted
    127:      * true, if soft deleted entries in the datasource should be counted, too
    128:      *
    129:      * @return int
    130:      * the count fulfilling the given parameters
    131:      */
    132:     public abstract function countBy($table, array $params, array $paramsOperators, $includeDeleted);
    133:
    134:     /**
    135:      * Adds the id and name of referenced entities to the given entity. Each
    136:      * reference field is before the raw id of the referenced entity and after
    137:      * the fetch, it's an array with the keys id and name.
    138:      *
    139:      * @param CRUDEntity $entity
    140:      * the entity to fetch the references for
    141:      */
    142:     public abstract function fetchReferences(CRUDEntity $entity = null);
    143:
    144:     /**
    145:      * Gets the {@see CRUDEntityDefinition} instance.
    146:      *
    147:      * @return CRUDEntityDefinition
    148:      * the definition instance
    149:      */
    150:     public function getDefinition() {
    151:         return $this->definition;
    152:     }
    153:
    154:     /**
    155:      * Creates a new, empty entity instance having all fields prefilled with
    156:      * null or the defined value in case of fixed fields.
    157:      *
    158:      * @return CRUDEntity
    159:      * the newly created entity
    160:      */
    161:     public function createEmpty() {
    162:         $entity = new CRUDEntity($this->definition);
    163:         $fields = $this->definition->getEditableFieldNames();
    164:         foreach ($fields as $field) {
    165:             $value = null;
    166:             if ($this->definition->getType($field) == 'fixed') {
    167:                 $value = $this->definition->getFixedValue($field);
    168:             }
    169:             $entity->set($field, $value);
    170:         }
    171:         $entity->set('id', null);
    172:         return $entity;
    173:     }
    174:
    175:     /**
    176:      * Creates the uploaded files of a newly created entity.
    177:      *
    178:      * @param Request $request
    179:      * the HTTP request containing the file data
    180:      * @param CRUDEntity $entity
    181:      * the just created entity
    182:      * @param string $entityName
    183:      * the name of the entity as this class here is not aware of it
    184:      */
    185:     public function createFiles(Request $request, CRUDEntity $entity, $entityName) {
    186:         $fields = $this->definition->getEditableFieldNames();
    187:         foreach ($fields as $field) {
    188:             if ($this->definition->getType($field) == 'file') {
    189:                 $this->fileProcessor->createFile($request, $entity, $entityName, $field);
    190:             }
    191:         }
    192:     }
    193:
    194:     /**
    195:      * Updates the uploaded files of an updated entity.
    196:      *
    197:      * @param Request $request
    198:      * the HTTP request containing the file data
    199:      * @param CRUDEntity $entity
    200:      * the updated entity
    201:      * @param string $entityName
    202:      * the name of the entity as this class here is not aware of it
    203:      */
    204:     public function updateFiles(Request $request, CRUDEntity $entity, $entityName) {
    205:         $fields = $this->definition->getEditableFieldNames();
    206:         foreach ($fields as $field) {
    207:             if ($this->definition->getType($field) == 'file') {
    208:                 $this->fileProcessor->updateFile($request, $entity, $entityName, $field);
    209:             }
    210:         }
    211:     }
    212:
    213:     /**
    214:      * Deletes a specific file from an existing entity.
    215:      *
    216:      * @param CRUDEntity $entity
    217:      * the entity to delete the file from
    218:      * @param string $entityName
    219:      * the name of the entity as this class here is not aware of it
    220:      * @param string $field
    221:      * the field of the entity containing the file to be deleted
    222:      */
    223:     public function deleteFile(CRUDEntity $entity, $entityName, $field) {
    224:         $this->fileProcessor->deleteFile($entity, $entityName, $field);
    225:     }
    226:
    227:     /**
    228:      * Deletes all files of an existing entity.
    229:      *
    230:      * @param CRUDEntity $entity
    231:      * the entity to delete the files from
    232:      * @param string $entityName
    233:      * the name of the entity as this class here is not aware of it
    234:      */
    235:     public function deleteFiles(CRUDEntity $entity, $entityName) {
    236:         $fields = $this->definition->getEditableFieldNames();
    237:         foreach ($fields as $field) {
    238:             if ($this->definition->getType($field) == 'file') {
    239:                 $this->fileProcessor->deleteFile($entity, $entityName, $field);
    240:             }
    241:         }
    242:     }
    243:
    244:     /**
    245:      * Renders (outputs) a file of an entity. This includes setting headers
    246:      * like the file size, mimetype and name, too.
    247:      *
    248:      * @param CRUDEntity $entity
    249:      * the entity to render the file from
    250:      * @param string $entityName
    251:      * the name of the entity as this class here is not aware of it
    252:      * @param string $field
    253:      * the field of the entity containing the file to be rendered
    254:      *
    255:      * @return Response
    256:      * the HTTP response, likely to be a streamed one
    257:      */
    258:     public function renderFile(CRUDEntity $entity, $entityName, $field) {
    259:         return $this->fileProcessor->renderFile($entity, $entityName, $field);
    260:     }
    261:
    262: }
    263: