Documentation

As said before, the Core module loads the modules you want to use in your website. These modules can then by used inside the Controllers of the website.

You can load these modules by using following code in your controllers:

•                                                         
  <?php
  class SomeNameController extends Controller
  {
      // Loading Core Classes
      private $DBconnect;
      private $SecondDB;
      private $Email;
      private $HttpRequest;
      private $Login;
      private $Menu;
  
  	public function __construct(array $args)
  	{
  		$Core = $args['Core'];
  		$this->DBconnect = $Core->DB['DBconnect'];
  		$this->SecondDB = $Core->DB['SecondDB'];
  		$this->Email = $Core->Email;
  		$this->HttpRequest = $Core->HttpRequest;
  		$this->Login = $Core->Login;
  		$this->Menu = $Core->Menu;
  	}
  
  	// Rest of the code which uses those modules, or loads them into Helper classes.
  
  }
                                                      

Of course, you only need to provide the code for those modules that you want to use or need in a specific controller.

In the example, two databases are loaded. The DBconnect is the most important one, because this one will be used in many of the other EasyMVC modules.

In practice, it almost never needs to be loaded in a controller, because, in most cases, this database connection will be automatically injected into the Repository or other classes that need it. It's merely when you have a second database, that this one will be loaded through the Controller. For now, the Repositories can only use the DBconnect connection when loaded through the Router. (See Router Module for more information about this.)

In most cases, this module doesn't need to be loaded into the controller when you use the Repository injection option of the router. It's only when you use more than one database, that the second database, and so on, need to be loaded into the controller. So, you can pass the connection to the Repository.

Because of this, the functions from the DBconnect class will be used inside the Repository- or Helper-classes.

For the following examples you can presume that $DBconnect stores the DBconnect class.

DBconnect functions (The old way).

query(string $query)

This function executes a query to the database.

Code example:

•                                                         
  $query = 'SELECT * FROM user ORDER BY id';
  $DBconnect->query($query);
                                                      

With this, all the users will be retrieved from the database and stored internally in the DBconnect object.

You can retrieve the number of rows affected by '$DBconnect->rows'. (See further for more information.)

If you want to get a certain user, you can use following code:

•                                                         
  $query = 'SELECT * FROM user WHERE id = ' . $DBconnect->cleanSQL($id);
  $DBconnect->query($query);
                                                      

fetchAll()

This will load the internal data into the publicly available $DBconnect-data variable.

Code example:

•                                                         
  $DBconnect->fetchAll();
  $name = $DBconnect->data[2]['name'];
  print('name: ' . $name);
                                                      

With this, the internal data is copied to the public data variable, and in the second line, the name of the third user is retrieved.

By using a for loop (in combination with $DBconnect-rows), or with a foreach loop, you could go through the whole dataset and print all the names. (Or add them to a separate array.)

fetchRow(int $id) (previous fetch(int $id)

This function can be used to retrieve a certain row of the internally stored data.

For loading the name of the third user, like in the previous example, following code can be used:

•                                                         
  $DBconnect->fetchRow(2);
  $name = $DBconnect->data['name'];
  print('name: ' . $name);
                                                      

queryRow(string $query) / Returns a Boolean

This function will perform a query against the database and store the first row in the public data variable. It will also return false if nothing was found, or true when data is present.

If you want to retrieve the third user from the database, you could use following code:

•                                                         
  $id = 2;
  $query = 'SELECT * FROM user WHERE id = ' . $DBconnect->cleanSQL($id);
  if ($DBconnect->queryRow($query)) {
      $name = $DBconnect->data['name'];
      print('name: ' . $name);
  }
                                                      

queryItem(string $query, string $field) / Returns a String

This function will perform a query against the database and return the value of a certain field.

If you want to retrieve just one field, like in our previous examples, you could even use following code:

•                                                         
  $id = 2;
  $query = 'SELECT * FROM user WHERE id = ' . $DBconnect->cleanSQL($id);
  $name = $DBconnect->queryItem($query, 'name');
  print('name: ' . $name);}
                                                      

insert(string $query) | update(string $query) | delete(string $query)

These functions can be used for an INSERT, UPDATE or DELETE SQL-query.

These could have been replaced by just one function, but for code clarity, it's good practice to make the function's name state what it is going to do!

lastInsertId($name = null)

This will return the id of the last inserted record into the database.

This can be very useful when you need to know the id when auto increment is active on the table.

cleanSQL(string $content = null) / Returns a String

To prevent SQL-injection from user inputs or manipulations, it is a good practice to use this function before adding the data to the query string.

This will use PDO's quote() function, but in the past, I had written a more complex code to make sure there was no SQL-injection possible, because of this, the cleanSQL() still exists in the DBconnect class.

DBconnect functions (Prepared Statement)

If you are using the prepared statement method, you don't need to learn any new syntax. DBconnect will use the same functions as PHP's PDO class. In this case, the DBconnect class is only used to make the connection with the database.

The code used above, would then look something like this:

•                                                         
  $id = 2;
  $statement = $DBconnect->prepare('SELECT * FROM user WHERE id = :id');
  $statement->bindValue(':id', $id, \PDO::PARAM_INT);
  $data = $statement->execute();
  $name = $data[0]['name'];
  print('name: ' . $name);}
                                                      

As it is obvious by its name, this module is used to send e-mails.

While it has been written to work within the EasyMVC framework, it can also be used as a standalone package.

At the initialization, the module will be loaded with the EMAIL_FROM address you have set in the config.php file. This can always be overridden by the function 'setFrom(string)'.

Email functions

setup(string $host, string $username, string $password, string $security)

You can use this function to override the settings of the SMTP-server you have set in the 'config.php'-file. This can be useful when you want to sent certain messages through another server.

Parameters

• $host: Name of your server
• $username / $password: Your credentials
• $security: ssl / tls / (empty)

emvc_config()

With this function, you can reset your SMTP-server settings to those you have set in your 'config.php'-file.

setFrom(string $from)

Setting your from-field of the e-mail.

Use '$...->setFrom()' if you want to reset is back to the default e-mail address you have set in your 'config.php'-file.

setTextMessage(array $to, string $subject, string $body, array $attachment, array $cc, array $bcc)

Use this function to prepare a plain text-message to be sent.

Parameters

• $to: e-mail address of the recipient
• $subject: Subject of the message
• $body: The message to be sent
• $attachment: File(s) you want to attach to the message
• $cc: e-mail address of the other recipients
• $bcc: e-mail address of the other recipients (hidden)

Code example:

•                                                         
  $mail = new Email('from@easymvc.be');
  $text = "Hello,\n\nThis is a test message.\n\nRegards,\nEasyMVC";
  $mail->setTextMessage('to@somewhere.com', 'Test Message', $text);
                                                      

setHtmlMessage(array $to, string $subject, string $body, array $attachment, array $cc, array $bcc)

Use this function to prepare a HTML-message to be sent.

Parameters

• $to: e-mail address of the recipient
• $subject: Subject of the message
• $body: The message to be sent
• $attachment: File(s) you want to attach to the message
• $cc: e-mail address of the other recipients
• $bcc: e-mail address of the other recipients (hidden)

Code example:

•                                                         
  $mail = new Email('from@easymvc.be');
  $html = "<p>Hello,</p><br><p>This is a test message.</p><br><p>Regards,<br>EasyMVC</p>";
  $mail->setTextMessage('to@somewhere.com', 'Test Message', $html);
                                                      

For more complex HTML-messages, I would suggest to use the Latte engine which is included with this module.

sendMail()

After you have prepared your message, you just need to use this function to sent it.

Depending on previous settings, it will use the SMTP-server you have set up, or else it will use the PHP internal mail() function.

emvcRenderHtml(string $latteFile, array $data) / Returns a string

With this function, you can create HTML-message by using the Latte template engine.

Parameters

• $latteFile: The name of the template-file to use
• $data: The data you want to use inside the latte file

The Latte template-files need to be stored inside the folder /private/latte.

For more information about Latte, check out latte.nette.org

This module is used to sent HttpRequests to APIs. It uses Guzzle, a famous PHP HTTP client library for which this module is a wrapper to make it easier to use it with EasyMVC.

HttpRequest functions

setBaseUel(string $baseUrl)

With this function, you can set a url's base address.

For example: $HttpRequest->setBaseUrl('http://api.website.be');

If you now want to do some request, you can use as url by those requests: '/api/users'.

This will translate to 'http://api.website.be/api/users'.

This is the preferred way of doing things, because if the url should change, you only have to edit one line in your code and not all lines where you do a HTTP-request.

getBaseUrl() / Returns a string

If you should need to url somewhere else in you code, you can retrieve it by this function.

Again, this will make it easier when the website's address would change.

get(string $url, string $username, string $password) / Returns a Response-object

With this you can sent a GET-request.

Parameters

• $url: The url of the API
• $username: The username to use with a secure API (optional)
• $password: The password to use with a secure API (optional)

These days, most of the time the response will be a JSON-string. You can retrieve this with: $response->getBody().

Other useful options are:

• ->getHeaders(): This will retrieve an array of all header information.
• ->getHeader('Content-Type'): This will retrieve the value of the header's Content-Type
• ->getStatusCode(): If everything went alright, it should have the value '200'
• ->getReasonPhrase(): For status code 200, it returns 'OK'
• ->getProtocolVersion(): The version of the protocol used, most cases this will be '1.1'

These can also be used on the other HTTP-requests.

post(string $url, string $body, string $username, string $password, string $contentType) / Returns a Response-object

put(string $url, string $body, string $username, string $password, string $contentType) / Returns a Response-object

patch(string $url, string $body, string $username, string $password, string $contentType) / Returns a Response-object

These functions look mostly the same for these three. It is, because all of them is to sent data to the API. Although, there are little differences!

A POST is used to send a new record to the API. If everything went right, the API's response should be '201' and in the body a reference for the resource location.

A PUT is used to update an existing record, and should include all fields for the record. The response should be '200'.

A PATCH is used to update an existing record, but only the fields that need to be updated are included. The response should be '200'.

Extra parameter

• $contentType: In most cases, you don't need to set this parameter. Its default value is 'application/json', which is used in most API calls these days. It's only here for the rare occasion that the API expects something else.

delete(string $url, string $username, string $password) / Returns a Response-object

This function is used to request the deletion of a record. No body is sent with this HTTP-requests!

The API normally will respond with a '200' (OK), but some APIs can also respond with a '202' (Accepted) or '204' (No Content). This is something that needs to be checked, or you could include all three options as a successful deletion of the record.

These are the HTTP-requests included in this module. If needed, other options can be added, but for now, these were all the requests I ever needed.

With this module, it's easy to implement a simple but secure authorization system for the website.

While the password is already salted by PHP itself, this module will add an extra salt-string to the password for increased security.

Preparing your database

The first thing you need to do, is to create the emvc_users table inside your database. This is the hard coded table that EasyMVC uses for the Login Module.

The easiest way to do this, is to run following SQL-queries with your preferred SQL-client. (This script was made with phpMyAdmin.)

•                                                         
  SET SQL_MODE = "NO_AUTO_VALUE_ON_ZERO";
  SET AUTOCOMMIT = 0;
  START TRANSACTION;
  SET time_zone = "+00:00";
  CREATE TABLE `emvc_users` (
    `id` int(11) NOT NULL,
    `username` varchar(40) NOT NULL,
    `email` varchar(70) NOT NULL,
    `password` varchar(255) NOT NULL,
    `salt` varchar(32) NOT NULL,
    `remember_me` varchar(40) NOT NULL,
    `remember_me_ip` varchar(45) NOT NULL,
    `access_level` int(2) NOT NULL
  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
  ALTER TABLE `emvc_users`
    ADD PRIMARY KEY (`id`),
    ADD UNIQUE KEY `username` (`username`),
    ADD UNIQUE KEY `email` (`email`);
  ALTER TABLE `emvc_users`
    MODIFY `id` int(11) NOT NULL AUTO_INCREMENT;
  COMMIT;
                                                      

!! Don't forget to mention to your visitors that the login system of your website will register their IP-address. This is needed for extra security, but the GDPR demands that you inform your visitors about this !!

Login functions

Getters & Setters

To access the user's data, you can use following getters:

• getId()
• getUsername()
• getEmail()
• getIP()
  • Will return the current IP-address of the user
• getData(string $key)
  • This getter is used to access extra fields that have been added to the table. However, the fields 'password', 'sald' and 'remember_me' can't be accessed with this.

To change any of the user's information use following setters:

• setUsername(string $username)
• setEmail(string $email)
• setPassword(string $password)
  • You only need this one to set the password for a new user! If you want to change the password of an existing user, use the function updatePassword(...)
• setData(string $key, mixed $value)
  • Again, this one is used to set the extra fields that have been added to the table. The 'password'-, 'salt'- and 'remember_me'-field can't be changed.

insertUser() / Returns a Boolean

This function will create a new user inside the emvc_users table and then sign in the user.

However, before you can use this function, you need to use all the setters to register the user's information.

The function will return 'true' if the account is created, and 'false' when something went wrong.

With $Login->errorCode you can check what went wrong.
If it returns '9', the username/email already exists.
If it returns '2', the account was created but the user couldn't be logged in.

loginUser(string $userLogin, string $password, bool $remember) / Returns a Boolean

To log in a user which already has an account.

Parameters

• $userLogin: username or e-mail depending on which log in is used
• $password: password that was provided at the log in
• $remember: If the user has to be remembered so he doesn't need to give his credentials at his next visit (Default = false)

Returns 'true' when successful, 'false' when credentials didn't match.

logoutUser(bool $cookie)

With this function the user is logged out of the system.

If $cookie is set to 'true', the user needs to provide his credentials the next time he visits the website.

checkUser() / Returns a Boolean

This function can be used to check if the user is logged in the system.

Returns 'true' if everything checks out, 'false' when something is wrong.

At the same time, the user data is loaded and can be accessed.

By adding a 'level'-field to the table, you could check the access level of the user and grant him access to a certain page or not.

updateUser(string $user) / Returns a Boolean

With this function the data of a user can be updated.

If you use $Login->updateUser(); the data of the logged in user is updated.

If you use $Login->updateUser('username'); the data of the user 'username' is updated.

Be careful when you update the data of another user!

Don't forget to update the user data with the setters before using this function.

Returns 'false' when the user to be updated can't be determined, 'true' when the user has been updated.

updatePassword(string $oldPassword, string $newPassword) / Returns a Boolean

This function will update the password of the user that is logged in.

It returns 'false' if the old password isn't right, 'true' when the update has been done.

resetPassword(string $login) / Returns a String or Boolean

Use this function to reset the password of a user. $login is the username or e-mail of the account.

Returns 'false' when the user couldn't be found, returns a random text which is needed by the next function.

createNewPassword(string $remember_me, string $password)

This function will set the new password for a certain user.

$remember_me is the random text from the previous function.

$password is the new password the user has provided.

This module is undergoing reconstructions. As soon as it is ready, the documentation will be added to the website.