An Entity instance represents a row in the database. In the example below, "User" is an entity class which maps object properties to database table fields. For example:

class User extends Entity 
{
    protected $id;
    protected $username;
    protected $email;
    protected $password;
    protected $name;
    protected $created_at; // automatically update
    protected $updated_at; // automatically update
}

Properties are defined as protected. If you add a "created_at" or "updated_at" property, they are automatically updated for you by Apify. When you want to access a property you can just write:

$user->email = 'me@email.com';
$email = $user->email;

You can define the getter and setter methods yourself. If a method exists Apify will use the existing accessors.

class User extends Entity 
{
    protected $id;
    protected $email;
    
    public function setEmail($email)
    {
        $this->email = $email;
    }
}

By default, the entity will be persisted to a table with the same name as the class name ("user"). In order to change that, you can call the setTable() method:

class UsersController extends Controller
{
    public function showAction($request)
    {
        $id = $request->getParam('id');
        
        // map the entity "User" to the table "users"
        $model = $this->getModel('User')->setTable('users');
        
        $response = new Response();
        $response->user = $model->find($id);
        
        return $response;
    }
}

Or you can create a Model class and overwrite the $table property as follows:

class UserModel extends Model
{
    // user-defined table
    protected $table = 'users';
    
    // user-defined method
    public function findByUsername($username)
    {
        // ...
    }
}

class UsersController extends Controller
{
    public function showAction($request)
    {
        $username = $request->getParam('username');

        $response = new Response();
        $response->user = $this->getModel('User')->findByUsername($username);
        
        return $response;
    }
}

Validating Entity Classes

Validating data before you send updates to the underlying database is a good practice that reduces errors:

class User extends Entity 
{
    protected $id;
    protected $email;
    
    // validate and sanitize input (optional)
    public function setEmail($value)
    {
        if (! filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new ValidationException('Invalid email address');
        }
        $this->email = trim($value);
    }
}

Because the validation is performed inside the class an exception is thrown if the value causes validation to fail. You can implement error handling for the code in your controller:

class UsersController extends Controller
{    
    public function updateAction($request)
    {
        if ('POST' != $request->getMethod()) {
            throw new Exception('HTTP method not supported', Response::NOT_ALLOWED);
        }
        
        $id = $request->getParam('id');
        
        $model = $this->getModel('User');
        $user = $model->find($id);
        if (! $user) {
            throw new Exception('User not found', Response::NOT_FOUND);
        }
        
        try {
            $user->email = $request->getPost('email'); // throws ValidationException
            $model->save($user); // throws ModelException
        } catch (ValidationException $e) {
            // do something
        } catch (ModelException $e) {
            // do something
        }
        
        return new Response();
    }
}