From ec03ddbc95679e43c0dcd7858ed301650bd068fc Mon Sep 17 00:00:00 2001 From: Titouan Galopin Date: Wed, 7 Sep 2016 17:16:42 +0200 Subject: [PATCH] Adapt and improve the documentation for new features --- README.md | 6 +- Resources/doc/01-installation.md | 7 +- Resources/doc/01a-orm-models.md | 50 ++++++------ Resources/doc/01b-odm-models.md | 36 +++++---- Resources/doc/02-basic-usage.md | 78 ++++++++++--------- Resources/doc/03-templating.md | 14 ++-- Resources/doc/05-permissions.md | 2 +- Resources/doc/06-events.md | 55 ++++++++++++- Resources/doc/90-multiple-recipients.md | 9 ++- .../90-sending-a-message-programatically.md | 18 ++--- Resources/doc/99-config-reference.md | 4 +- Resources/doc/99-using-other-user-bundles.md | 44 ++++++----- 12 files changed, 192 insertions(+), 131 deletions(-) diff --git a/README.md b/README.md index f373d7a5..bf1e6884 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Documentation Documentation for this bundle is stored under `Resources/doc` in this repository. -[Read the documentation for master][] +[Read the documentation for the last stable (1.3)][] License ------- @@ -24,7 +24,7 @@ License This bundle is under the MIT license. See the complete license in the bundle: ``` - Resources/meta/LICENSE +Resources/meta/LICENSE ``` -[Read the documentation for master]: https://github.com/FriendsOfSymfony/FOSMessageBundle/blob/master/Resources/doc/00-index.md +[Read the documentation for the last stable (1.3)]: https://github.com/FriendsOfSymfony/FOSMessageBundle/blob/master/Resources/doc/00-index.md diff --git a/Resources/doc/01-installation.md b/Resources/doc/01-installation.md index 6f4ed9db..f8c9298b 100644 --- a/Resources/doc/01-installation.md +++ b/Resources/doc/01-installation.md @@ -11,7 +11,7 @@ The first step is to tell composer that you want to download FOSMessageBundle wh be achieved by typing the following at the command prompt: ```bash -$ php composer.phar require friendsofsymfony/message-bundle +$ composer require friendsofsymfony/message-bundle ``` ### Step 2 - Setting up your user class @@ -24,6 +24,7 @@ Your user class may look something like the following: ```php get('fos_message.provider'); +$provider = $container->get('fos_message.provider'); - $threads = $provider->getInboxThreads(); +$threads = $provider->getInboxThreads(); ``` And the threads in the sentbox:: ```php - $threads = $provider->getSentThreads(); +$threads = $provider->getSentThreads(); ``` To get a single thread, check it belongs to the authenticated user and mark it as read:: ```php - $thread = $provider->getThread($threadId); +$thread = $provider->getThread($threadId); ``` Manipulate threads @@ -33,36 +33,40 @@ Manipulate threads See `FOS\\MessageBundle\\Model\\ThreadInterface` for the complete list of available methods:: ```php - // Print the thread subject - echo $thread->getSubject(); +// Print the thread subject +echo $thread->getSubject(); - // Get the tread participants - $participants = $thread->getParticipants(); +// Get the tread participants +$participants = $thread->getParticipants(); - // Know if this participant has read this thread - if ($thread->isReadByParticipant($participant)) +// Know if this participant has read this thread +if ($thread->isReadByParticipant($participant)) - // Know if this participant has deleted this thread - if ($thread->isDeletedByParticipant($participant)) +// Know if this participant has deleted this thread +if ($thread->isDeletedByParticipant($participant)) ``` +Be careful when manipulating thread participants: you may have to persist the thread to synchronize +the thread metadata using `$container->get('fos_message.thread_manager')->saveThread($thread, false)` +(the second argument as `false` meaning to not flush the modifications). + Manipulate messages ------------------- See ``FOS\\MessageBundle\\Model\\MessageInterface`` for the complete list of available methods:: ```php - // Print the message body - echo $message->getBody(); +// Print the message body +echo $message->getBody(); - // Get the message sender participant - $sender = $message->getSender(); +// Get the message sender participant +$sender = $message->getSender(); - // Get the message thread - $thread = $message->getThread(); +// Get the message thread +$thread = $message->getThread(); - // Know if this participant has read this message - if ($message->isReadByParticipant($participant)) +// Know if this participant has read this message +if ($message->isReadByParticipant($participant)) ``` Compose a message @@ -71,23 +75,23 @@ Compose a message Create a new message thread:: ```php - $composer = $container->get('fos_message.composer'); - - $message = $composer->newThread() - ->setSender($jack) - ->addRecipient($clyde) - ->setSubject('Hi there') - ->setBody('This is a test message') - ->getMessage(); +$composer = $container->get('fos_message.composer'); + +$message = $composer->newThread() + ->setSender($jack) + ->addRecipient($clyde) + ->setSubject('Hi there') + ->setBody('This is a test message') + ->getMessage(); ``` And to reply to this thread:: ```php - $message = $composer->reply($thread) - ->setSender($clyde) - ->setBody('This is the answer to the test message') - ->getMessage(); +$message = $composer->reply($thread) + ->setSender($clyde) + ->setBody('This is the answer to the test message') + ->getMessage(); ``` Note that when replying, we don't need to provide the subject nor the recipient. @@ -99,9 +103,8 @@ Send a message Nothing's easier than sending the message you've just composed:: ```php - $sender = $container->get('fos_message.sender'); - - $sender->send($message); +$sender = $container->get('fos_message.sender'); +$sender->send($message); ``` Number of Unread Messages @@ -110,9 +113,8 @@ Number of Unread Messages You can return the number of unread messages for the authenticated user with:: ```php - $provider = $container->get('fos_message.provider'); - - $provider->getNbUnreadMessages() +$provider = $container->get('fos_message.provider'); +$provider->getNbUnreadMessages(); ``` Will return an integer, the number of unread messages. diff --git a/Resources/doc/03-templating.md b/Resources/doc/03-templating.md index ac0d10be..156aff7b 100644 --- a/Resources/doc/03-templating.md +++ b/Resources/doc/03-templating.md @@ -4,16 +4,16 @@ Templating Helpers for FOSMessageBundle MessageBundle provides a few twig functions:: ```html+jinja - {# template.html.twig #} +{# template.html.twig #} - {# Know if a message is read by the authenticated participant #} - {% if not fos_message_is_read(message) %} This message is new! {% endif %} +{# Know if a message is read by the authenticated participant #} +{% if not fos_message_is_read(message) %} This message is new! {% endif %} - {# Know if a thread is read by the authenticated participant. Yes, it's the same function. #} - {% if not fos_message_is_read(thread) %} This thread is new! {% endif %} +{# Know if a thread is read by the authenticated participant. Yes, it's the same function. #} +{% if not fos_message_is_read(thread) %} This thread is new! {% endif %} - {# Get the number of new threads for the authenticated participant #} - You have {{ fos_message_nb_unread() }} new messages +{# Get the number of new threads for the authenticated participant #} +You have {{ fos_message_nb_unread() }} new messages ``` [Return to the documentation index](00-index.md) diff --git a/Resources/doc/05-permissions.md b/Resources/doc/05-permissions.md index 221906e3..ccecc650 100644 --- a/Resources/doc/05-permissions.md +++ b/Resources/doc/05-permissions.md @@ -11,7 +11,7 @@ FOSMessageBundle about it: # app/config/config.yml fos_message: - authorizer: acme_message.authorizer + authorizer: app.authorizer ``` Any such service must implement `FOS\MessageBundle\Security\AuthorizerInterface`. diff --git a/Resources/doc/06-events.md b/Resources/doc/06-events.md index 3034f1ed..d9c7676d 100644 --- a/Resources/doc/06-events.md +++ b/Resources/doc/06-events.md @@ -4,7 +4,58 @@ FOSMessageBundle Events FOSMessageBundle will dispatch events inside the Symfony2 `EventDispatcher` which allows you to write listeners to modify or augment behaviour of the MessageBundle process. -You can see definitions and explanations of each event as defined in -`Event\FOSMessageEvents`. +You can see definitions and explanations of each event as defined in `Event\FOSMessageEvents`: + +```php +get('security.context')->getToken()->getUser(); - $threadBuilder = $this->get('fos_message.composer')->newThread(); - $threadBuilder - ->addRecipient($recipient) // Retrieved from your backend, your user manager or ... - ->setSender($sender) - ->setSubject('Stof commented on your pull request #456789') - ->setBody('You have a typo, : mondo instead of mongo. Also for coding standards ...'); +$sender = $this->get('security.context')->getToken()->getUser(); +$threadBuilder = $this->get('fos_message.composer')->newThread(); +$threadBuilder + ->addRecipient($recipient) // Retrieved from your backend, your user manager or ... + ->setSender($sender) + ->setSubject('Stof commented on your pull request #456789') + ->setBody('You have a typo, : mondo instead of mongo. Also for coding standards ...'); ``` Sending a message @@ -33,8 +33,8 @@ Sending a message Now all you have to do to send your message is get the sender and tell it to send ```php - $sender = $this->get('fos_message.sender'); - $sender->send($threadBuilder->getMessage()); +$sender = $this->get('fos_message.sender'); +$sender->send($threadBuilder->getMessage()); ``` That's it, your message should now have been sent diff --git a/Resources/doc/99-config-reference.md b/Resources/doc/99-config-reference.md index d85a58dd..b7f5a391 100644 --- a/Resources/doc/99-config-reference.md +++ b/Resources/doc/99-config-reference.md @@ -8,8 +8,8 @@ All configuration options are listed below:: fos_message: db_driver: orm - thread_class: Acme\MessageBundle\Entity\Thread - message_class: Acme\MessageBundle\Entity\Message + thread_class: AppBundle\Entity\Thread + message_class: AppBundle\Entity\Message message_manager: fos_message.message_manager # See ModelManager\MessageManagerInterface thread_manager: fos_message.thread_manager # See ModelManager\ThreadManagerInterface sender: fos_message.sender # See Sender\SenderInterface diff --git a/Resources/doc/99-using-other-user-bundles.md b/Resources/doc/99-using-other-user-bundles.md index 206dc925..484d99d5 100644 --- a/Resources/doc/99-using-other-user-bundles.md +++ b/Resources/doc/99-using-other-user-bundles.md @@ -13,15 +13,16 @@ You can base your own on this one: ``` php repository = $doctrine->getManager()->getRepository('AcmeUserBundle:User'); + $this->repository = $doctrine->getManager()->getRepository('AppBundle:User'); } /** @@ -57,7 +58,7 @@ class UserToUsernameTransformer implements DataTransformerInterface } if (! $value instanceof User) { - throw new UnexpectedTypeException($value, 'Acme\UserBundle\Entity\User'); + throw new UnexpectedTypeException($value, 'AppBundle\Entity\User'); } return $value->getUsername(); @@ -92,15 +93,15 @@ For the moment, there is no configuration key to do it so we will emulate the FOSUserBundle transformer by using its name as an alias of our own service: ``` xml - + + + - + ``` - - ### Problems you may encounter #### User identifier field is not `id` @@ -113,28 +114,31 @@ You can copy the default ones (in `FOS\MessageBundle\EntityManager` if you use t into your bundle, change their queries and register them as services: ``` xml - + + + %fos_message.message_class% %fos_message.message_meta_class% - + %fos_message.thread_class% %fos_message.thread_meta_class% - + ``` Once done, tell FOSMessageBundle to use them in the configuration: ``` yaml -# Messages +# app/config/config.yml + fos_message: # ... - thread_manager: acme_user.thread_manager - message_manager: acme_user.message_manager + thread_manager: app.thread_manager + message_manager: app.message_manager ``` #### The default form does not work with my User entity @@ -146,11 +150,11 @@ You have to redefine two things : You can copy and paste the bundle versions into your application and define them as services: ``` xml - - + + - + %fos_message.new_thread_form.name% @@ -163,11 +167,13 @@ You can copy and paste the bundle versions into your application and define them And configure the bundle to use your services: ``` yaml +# app/config/config.yml + fos_message: # ... new_thread_form: - type: md.new_thread_form_type - factory: md.new_thread_form_factory + type: app.new_thread_form_type + factory: app.new_thread_form_factory ``` #### Another problem?