README

Contactable module for Nette framework and Doctrine.

Installation

$ composer require carrooi/contactable
$ composer update

Configuration

extensions:
	contactable: Carrooi\Contactable\DI\ContactableExtension

contactable:
	contactItemClass: App\Model\Entities\ContactItem
	associations:
		App\Model\Entities\User: user

contactItemClass: entity with associations between contact types and eg. user entity
associations: list of contactable entities with field names which are manyToOne associations in contactItemClass

Contactable entity

Entity which implements Carrooi\Contactable\Model\Entities\IContactableEntity interface with these methods:

getId(): returns identifier
getContacts(): returns array of Carrooi\Contactable\Model\Entities\IContactItem entities
addContact(): adds new Carrooi\Contactable\Model\Entities\IContactItem entity to collection
removeContact(): removes Carrooi\Contactable\Model\Entities\IContactItem entity from collection

Of course you don't need to implement all required methods on your own (except for getId() method). Just use prepared trait Carrooi\Contactable\Model\Entities\TContactable.

namespace App\Model\Entities;

use Carrooi\Contactable\Model\Entities\IContactableEntity;
use Carrooi\Contactable\Model\Entities\TContactable;
use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity
 * @author David Kudera
 */
class User implements IContactableEntity
{

	use TContactable;

	// ...

	/**
	 * @return int
	 */
	public function getId()
	{
		return $this->id;
	}

}

Contact item entity

Entity which holds the actual value of contact, eg. actual email address of user. This entity must implement Carrooi\Contactable\Model\Entities\IContactItem interface with these methods:

getId(): returns identifier
getContactType() returns Carrooi\Contactable\Model\Entities\IContactType entity
setContactType() sets Carrooi\Contactable\Model\Entities\IContactType entity
getValue(): returns value of contact
setValue(): sets value of contact
validateValue() validate value against pattern in contact type

Again, you can use prepared trait Carrooi\Contactable\Model\Entities\TContactItem.

namespace App\Model\Entities;

use Carrooi\Contactable\Model\Entities\IContactItem;
use Carrooi\Contactable\Model\Entities\TContactItem;
use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity
 * @author David Kudera
 */
class ContactItem implements IContactItem
{

	use TContactItem;

	/**
	 * @ORM\Id
	 * @ORM\Column(type="integer")
	 * @var int
	 */
	private $id;

	/**
	 * @ORM\ManyToOne(targetEntity="\App\Model\Entities\User")
	 * @var \App\Model\Entities\User
	 */
	private $user;

	// ... some getters and setters for all fields

}

As you can see, we've got user field which corresponding with associations setup in your configuration.

Contact types

You can create as many types as you want, eg. mails, facebook, phone numbers etc.

There is already prepared service for that: Carrooi\Contactable\Model\Facades\ContactTypesFacade.

Create contact type:

$type = $types->create('mail', 'Email', [
	'pattern' => '[a-z]+@[a-z]+\.[a-z]{2,3}',    // really naive mail regex
	'url' => 'mail.org',
]);

arguments:

name: required "system" name
title: required "public" name
values:
- not required list of other values
- pattern: not required pattern for all contact values of this type
- url: not required url to contact

Update contact type:

$types->update($type, [
	'name' => 'email',
	'title' => 'Email address',
	'pattern' => '.+',            // no more naive, just stupid
	'url' => 'mail.com',
]);

Remove contact type:

$types->remove($type);

Get all contact types:

foreach ($types->findAll() as $type) {
	// ...
}

Get id => names pairs:

foreach ($types->findAllNames() as $id => $name) {
	// ...
}

Find contact type by id:

$type = $types->findOneById($id);

Find contact type by name:

$type = $types->findOneByName($name);

Contact items facade

There is also service Carrooi\Contactable\Model\Facades\ContactItemsFacade which can be used for adding contacts to contactable entities.

Add contact:

$item = $items->addContact($user, $type, 'lorem@ipsum.com');

Update contact:

$items->update($item, [
	'contactType' => $anotherType,
	'value' => '999888777',
]);

Remove contact:

$items->remove($item);

Find by id:

$item = $items->findOneById($id);

Find all by entity:

foreach ($items->findAllByEntity($user) as $item) {
	// ...
}

Changelog

1.0.0
- Initial version

carrooi / contactable

Maintainers

Details