Records are objects representing a single row (tuple) of a SQL table and provide an an interface for interacting with that row. It provides CRUD (Create Read Update Delete) functionality as well as field data verification.

Records should be stored in

app/record/

You must use the Disco CLI to create your records.

Lets establish a user table for our example:

user

  • id INT(11) PK AI
  • name VARCHAR(120) NOT NULL
  • email VARCHAR(400) NOT NULL
  • age INT(3) NULL
  • bio TEXT NULL

 

Records depend on your DB settings in app/config/config.php.

Basic Examples #

$record = new App\record\User;

// Lets populate the record with some data
$record->name = 'Johnny B Good'
$record['email'] = 'johnny@mail.com'


// Create/Insert
$record->insert();

// Auto increment primary keys will be set when an insert is performed
echo $record->id;


// Update
$record->bio = 'I like biking and fishing.'
$record['age'] = 28;
$record->update();


// Delete
$record->delete();


// Pass an array to the constructor to pre-seed a record with values
$record = new App\record\User(['id' => 20, 'name' => 'Will']);

Validation #

Validation is the adherence of a fields value to its defined data type. For example if a field is a CHAR(1) and you try to insert 'abc' you are going to get only 'a' or if you try and insert an integer you will get an error.

Records perform validation of their fields based on the field type defined by its corresponding field on the SQL table. When data does not adhere to its defined condition a `Disco\classes\RecordValidation` exception will be thrown when attempting to perform INSERTS, UPDATES, or DELETES.

If you attempt to UPDATE or DELETE a record that does not have its primary keys set a `Disco\classes\RecordId` exception will be thrown.

If you attempt to INSERT a record that has null field values that cannot be null a `Disco\classes\Record` exception will be thrown.

All records exceptions thrown extend the `Disco\classes\Record` exception.

Examples:

$record = new App\record\User;

$record->name = 'Bob';


// Checking validation yourself
$valid = $record->validateField('name');
echo $valid; // `true`


// Inserting with null values when there are required fields
try {
    $record->insert();
} catch(Disco\classes\Record $e){
    echo $e->getMessage(); // `Record insert error : fields 'email' cannot be null`
}

$record = new App\record\User;

// Updating with null primary keys
try {
    $record->name = 'Kevin';
    $record->update();
} catch(Disco\classes\RecordId $e){
    echo $e->getMessage(); // `Record use/modification attempted with null id(s)`
}

$record = new App\record\User(['id' => 2]);

// Updating with invalid data
// Remember age can only be 3 digits long!
try {
    $record->age = 1500;
    $record->update();
} catch(Disco\classes\RecordValidation $e){
    echo $e->getMessage(); // `Record validation error - Field : 'age' Value : 1500`
}

When performing UPDATES on a record you do not have to have all the required fields set on the model, only the ones needing updating. You do however have to have the primary keys set!

Fetching Fields #

$record = new App\record\User(['id' => 243, 'name' => 'Billy']);

// Get all the fields set on the record
$fields = $record->getFields();

// Get fields that are not set on the record
// The fetched field will be returned as well
// as set internally on the record
$fields = $record->fetch(['age']);
$record->fetch('bio');

// Get all the fields that are not set on the record
$fields = $record->fetchMissing();

You should use the fetch method with caution, as every time you use it the record must make a request to the SQL database. Do not use it in tight loops or for population of many records. Use a model to select what you need and instantiate records with the result set rows from the query passed into the record constructor.

Finding Records #

// Find a record with the static find method using the first 
// parameter as the where condition and the second as the fields to select

$record = App\record\User::find(['id' => 58], ['id','name','bio']);

if($record !== false){
    // The record exists!
    // Do something with it
}