BCard - Documentation technique

EmployeeApiController extends AbstractController
in package

Contrôleur d'API de gestion des employés rattachés à un compte entreprise.

Il expose un CRUD complet sur les employés (liste paginée, détail avec les cartes de visite associées, création, mise à jour, suppression). La liste et la création exigent en plus que l'utilisateur authentifié dispose d'une entreprise et d'un compte activé ; le détail, la mise à jour et la suppression s'appuient sur un contrôle de propriété avec dérogation pour ROLE_ADMIN.

Préfixe de route : /api/employees. Toutes les actions exigent IS_AUTHENTICATED_FULLY (jeton JWT bearerAuth).

Attributes
#[Route]
'/api/employees'
$name: 'api_employees_'
#[Tag]
$name: 'Employees'
$description: 'Gestion des employés'

Table of Contents

Properties

$entityManager  : EntityManagerInterface
$validator  : ValidatorInterface

Methods

__construct()  : mixed
create()  : JsonResponse
Crée un employé pour l'entreprise de l'utilisateur.
delete()  : JsonResponse
Supprime un employé de l'entreprise.
list()  : JsonResponse
Retourne la liste paginée des employés de l'entreprise de l'utilisateur.
show()  : JsonResponse
Retourne le détail d'un employé et ses cartes de visite.
update()  : JsonResponse
Met à jour un employé existant.

Properties

Methods

__construct()

public __construct(EntityManagerInterface $entityManager, ValidatorInterface $validator) : mixed
Parameters
$entityManager : EntityManagerInterface

Gestionnaire d'entités Doctrine, utilisé pour les dépôts, la persistance et la suppression.

$validator : ValidatorInterface

Validateur appliqué à l'entité Employee avant écriture.

create()

Crée un employé pour l'entreprise de l'utilisateur.

public create(Request $request) : JsonResponse

Exige un compte entreprise activé, puis contrôle la présence non vide des champs firstname, lastname et email. L'unicité de l'email est vérifiée dans le périmètre de l'utilisateur courant uniquement. Les champs phone, position et department sont optionnels et valorisés à null s'ils sont absents. L'entité est validée avant persistance.

Remarque : l'employé créé n'est pas explicitement rattaché à l'utilisateur courant dans cette méthode, alors que les contrôles de doublon et les autres actions s'appuient sur cette association.

Route : /api/employees (POST), nom api_employees_create. Requiert IS_AUTHENTICATED_FULLY.

Corps attendu : {"firstname": "string — obligatoire", "lastname": "string — obligatoire", "email": "string — obligatoire, unique pour l'entreprise", "phone": "string — optionnel", "position": "string — optionnel", "department": "string — optionnel"}

Réponses : 201 employé créé ({message, employee_id}), 400 champ obligatoire manquant ou vide, 400 email déjà utilisé par un employé, 400 violations de contraintes ({"errors": [...]}), 403 utilisateur sans entreprise ou compte non activé, 401 requête non authentifiée.

Parameters
$request : Request

Requête HTTP dont le corps JSON décrit l'employé à créer.

Attributes
#[IsGranted]
'IS_AUTHENTICATED_FULLY'
#[Post]
$path: '/api/employees'
$description: 'Crée un nouvel employé pour l\'entreprise'
$summary: 'Crée un nouvel employé'
$security: [['bearerAuth' => []]]
$requestBody: new OA\RequestBody(required: true, content: new OA\JsonContent(required: ['firstname', 'lastname', 'email'], properties: [new OA\Property(property: 'firstname', type: 'string', example: 'John'), new OA\Property(property: 'lastname', type: 'string', example: 'Doe'), new OA\Property(property: 'email', type: 'string', example: 'john@example.com'), new OA\Property(property: 'phone', type: 'string', example: '+33123456789'), new OA\Property(property: 'position', type: 'string', example: 'Développeur'), new OA\Property(property: 'department', type: 'string', example: 'IT')]))
$tags: ['Employees']
$responses: [new OA\Response(response: 201, description: 'Employé créé avec succès', content: new OA\JsonContent(properties: [new OA\Property(property: 'message', type: 'string', example: 'Employé créé avec succès'), new OA\Property(property: 'employee_id', type: 'integer', example: 1)])), new OA\Response(response: 400, description: 'Données invalides'), new OA\Response(response: 401, description: 'Non authentifié'), new OA\Response(response: 403, description: 'Accès refusé - Compte entreprise requis')]
#[Route]
''
$name: 'create'
$methods: ['POST']
Return values
JsonResponse —

Message de confirmation et identifiant du nouvel employé, ou erreurs.

delete()

Supprime un employé de l'entreprise.

public delete(int $id, EmployeeRepository $employeeRepository) : JsonResponse

Après contrôle de propriété (avec dérogation ROLE_ADMIN), l'entité est retirée définitivement de la base. Aucune vérification préalable des cartes de visite rattachées n'est effectuée : leur sort dépend de la configuration des cascades Doctrine sur l'association.

Route : /api/employees/{id} (DELETE), nom api_employees_delete. Requiert IS_AUTHENTICATED_FULLY.

Réponses : 200 employé supprimé, 403 employé appartenant à un autre utilisateur (hors administrateur), 404 employé inexistant, 401 requête non authentifiée.

Parameters
$id : int

Identifiant de l'employé à supprimer.

$employeeRepository : EmployeeRepository

Dépôt utilisé pour retrouver l'employé.

Attributes
#[Delete]
$path: '/api/employees/{id}'
$description: 'Supprime un employé de l\'entreprise'
$summary: 'Supprime un employé'
$security: [['bearerAuth' => []]]
$tags: ['Employees']
$parameters: [new OA\Parameter(name: 'id', description: 'ID de l\'employé à supprimer', in: 'path', required: true, schema: new OA\Schema(type: 'integer'))]
$responses: [new OA\Response(response: 200, description: 'Employé supprimé avec succès', content: new OA\JsonContent(properties: [new OA\Property(property: 'message', type: 'string', example: 'Employé supprimé avec succès')])), new OA\Response(response: 404, description: 'Employé non trouvé'), new OA\Response(response: 403, description: 'Accès refusé')]
#[IsGranted]
'IS_AUTHENTICATED_FULLY'
#[Route]
'/{id}'
$name: 'delete'
$methods: ['DELETE']
Return values
JsonResponse —

Message de confirmation, ou message d'erreur sous la clé error.

list()

Retourne la liste paginée des employés de l'entreprise de l'utilisateur.

public list(Request $request, EmployeeRepository $employeeRepository) : JsonResponse

Exige d'abord que l'utilisateur possède une entreprise et un compte activé. Les employés sont ensuite filtrés sur l'utilisateur courant et triés par created_at décroissant ; page est ramené à 1 au minimum et limit est borné à l'intervalle [1, 50] (défaut 10). Pour chaque employé, le nombre de cartes de visite associées est calculé en comptant la collection businessCardAizes.

Route : /api/employees (GET), nom api_employees_list. Requiert IS_AUTHENTICATED_FULLY.

Paramètres de requête : page (optionnel, défaut 1), limit (optionnel, défaut 10, plafonné à 50).

Réponses : 200 liste renvoyée, 403 utilisateur sans entreprise ou compte non activé, 401 requête non authentifiée.

Parameters
$request : Request

Requête HTTP portant les paramètres de pagination.

$employeeRepository : EmployeeRepository

Dépôt utilisé pour la recherche et le comptage.

Attributes
#[Get]
$path: '/api/employees'
$description: 'Récupère la liste des employés de l\'entreprise de l\'utilisateur connecté'
$summary: 'Liste les employés de l\'entreprise'
$security: [['bearerAuth' => []]]
$tags: ['Employees']
$parameters: [new OA\Parameter(name: 'page', description: 'Numéro de page', in: 'query', required: false, schema: new OA\Schema(type: 'integer', default: 1)), new OA\Parameter(name: 'limit', description: 'Nombre d\'éléments par page', in: 'query', required: false, schema: new OA\Schema(type: 'integer', default: 10))]
$responses: [new OA\Response(response: 200, description: 'Liste des employés récupérée avec succès', content: new OA\JsonContent(properties: [new OA\Property(property: 'employees', type: 'array', items: new OA\Items(properties: [new OA\Property(property: 'id', type: 'integer', example: 1), new OA\Property(property: 'firstname', type: 'string', example: 'John'), new OA\Property(property: 'lastname', type: 'string', example: 'Doe'), new OA\Property(property: 'email', type: 'string', example: 'john@example.com'), new OA\Property(property: 'phone', type: 'string', example: '+33123456789'), new OA\Property(property: 'position', type: 'string', example: 'Développeur'), new OA\Property(property: 'department', type: 'string', example: 'IT'), new OA\Property(property: 'created_at', type: 'string', format: 'date-time'), new OA\Property(property: 'business_cards_count', type: 'integer', example: 2)])), new OA\Property(property: 'pagination', properties: [new OA\Property(property: 'current_page', type: 'integer'), new OA\Property(property: 'total_pages', type: 'integer'), new OA\Property(property: 'total_items', type: 'integer'), new OA\Property(property: 'items_per_page', type: 'integer')], type: 'object')])), new OA\Response(response: 401, description: 'Non authentifié'), new OA\Response(response: 403, description: 'Accès refusé - Compte entreprise requis')]
#[IsGranted]
'IS_AUTHENTICATED_FULLY'
#[Route]
''
$name: 'list'
$methods: ['GET']
Return values
JsonResponse —

Objet JSON {employees: list<array<string, mixed>>, pagination: array<string, int|float>}.

show()

Retourne le détail d'un employé et ses cartes de visite.

public show(int $id, EmployeeRepository $employeeRepository) : JsonResponse

L'employé est chargé par sa clé primaire, puis un contrôle de propriété est appliqué : seul l'utilisateur propriétaire, ou un porteur de ROLE_ADMIN, y a accès. La charge utile inclut la liste complète, non paginée, des cartes de visite rattachées à l'employé. Contrairement à EmployeeApiController::list(), aucune vérification du statut entreprise ou d'activation n'est effectuée ici.

Route : /api/employees/{id} (GET), nom api_employees_show. Requiert IS_AUTHENTICATED_FULLY.

Réponses : 200 employé renvoyé, 403 employé appartenant à un autre utilisateur (hors administrateur), 404 employé inexistant, 401 requête non authentifiée.

Parameters
$id : int

Identifiant de l'employé, issu du chemin.

$employeeRepository : EmployeeRepository

Dépôt utilisé pour retrouver l'employé.

Attributes
#[Get]
$path: '/api/employees/{id}'
$description: 'Récupère les détails d\'un employé spécifique'
$summary: 'Récupère un employé par son ID'
$security: [['bearerAuth' => []]]
$tags: ['Employees']
$parameters: [new OA\Parameter(name: 'id', description: 'ID de l\'employé', in: 'path', required: true, schema: new OA\Schema(type: 'integer'))]
$responses: [new OA\Response(response: 200, description: 'Détails de l\'employé', content: new OA\JsonContent(properties: [new OA\Property(property: 'id', type: 'integer', example: 1), new OA\Property(property: 'firstname', type: 'string', example: 'John'), new OA\Property(property: 'lastname', type: 'string', example: 'Doe'), new OA\Property(property: 'email', type: 'string', example: 'john@example.com'), new OA\Property(property: 'phone', type: 'string', example: '+33123456789'), new OA\Property(property: 'position', type: 'string', example: 'Développeur'), new OA\Property(property: 'department', type: 'string', example: 'IT'), new OA\Property(property: 'created_at', type: 'string', format: 'date-time'), new OA\Property(property: 'business_cards', type: 'array', items: new OA\Items(properties: [new OA\Property(property: 'id', type: 'integer'), new OA\Property(property: 'firstname', type: 'string'), new OA\Property(property: 'lastname', type: 'string'), new OA\Property(property: 'email', type: 'string'), new OA\Property(property: 'phone', type: 'string'), new OA\Property(property: 'position', type: 'string'), new OA\Property(property: 'created_at', type: 'string', format: 'date-time')]))])), new OA\Response(response: 404, description: 'Employé non trouvé'), new OA\Response(response: 403, description: 'Accès refusé')]
#[IsGranted]
'IS_AUTHENTICATED_FULLY'
#[Route]
'/{id}'
$name: 'show'
$methods: ['GET']
Return values
JsonResponse —

Objet JSON {id, firstname, lastname, email, phone, position, department, created_at, business_cards} ou message d'erreur.

update()

Met à jour un employé existant.

public update(int $id, Request $request, EmployeeRepository $employeeRepository) : JsonResponse

Après contrôle de propriété (avec dérogation ROLE_ADMIN), seuls les champs réellement présents dans le corps JSON sont appliqués : la requête se comporte comme une mise à jour partielle malgré le verbe PUT. La modification de l'email déclenche une vérification d'unicité restreinte aux autres employés du même utilisateur, l'employé courant étant exclu de la requête. L'entité est validée avant flush().

Route : /api/employees/{id} (PUT), nom api_employees_update. Requiert IS_AUTHENTICATED_FULLY.

Corps attendu (toutes les clés optionnelles) : {"firstname": "string", "lastname": "string", "email": "string — contrôlé en unicité", "phone": "string", "position": "string", "department": "string"}

Réponses : 200 employé mis à jour, 400 email déjà utilisé par un autre employé, 400 violations de contraintes ({"errors": [...]}), 403 employé appartenant à un autre utilisateur (hors administrateur), 404 employé inexistant, 401 requête non authentifiée.

Parameters
$id : int

Identifiant de l'employé à mettre à jour.

$request : Request

Requête HTTP dont le corps JSON porte les champs à modifier.

$employeeRepository : EmployeeRepository

Dépôt utilisé pour retrouver l'employé.

Attributes
#[IsGranted]
'IS_AUTHENTICATED_FULLY'
#[Put]
$path: '/api/employees/{id}'
$description: 'Met à jour les informations d\'un employé'
$summary: 'Met à jour un employé'
$security: [['bearerAuth' => []]]
$requestBody: new OA\RequestBody(required: true, content: new OA\JsonContent(properties: [new OA\Property(property: 'firstname', type: 'string', example: 'John'), new OA\Property(property: 'lastname', type: 'string', example: 'Doe'), new OA\Property(property: 'email', type: 'string', example: 'john@example.com'), new OA\Property(property: 'phone', type: 'string', example: '+33123456789'), new OA\Property(property: 'position', type: 'string', example: 'Développeur Senior'), new OA\Property(property: 'department', type: 'string', example: 'IT')]))
$tags: ['Employees']
$parameters: [new OA\Parameter(name: 'id', description: 'ID de l\'employé à mettre à jour', in: 'path', required: true, schema: new OA\Schema(type: 'integer'))]
$responses: [new OA\Response(response: 200, description: 'Employé mis à jour avec succès', content: new OA\JsonContent(properties: [new OA\Property(property: 'message', type: 'string', example: 'Employé mis à jour avec succès')])), new OA\Response(response: 400, description: 'Données invalides'), new OA\Response(response: 404, description: 'Employé non trouvé'), new OA\Response(response: 403, description: 'Accès refusé')]
#[Route]
'/{id}'
$name: 'update'
$methods: ['PUT']
Return values
JsonResponse —

Message de confirmation, ou erreurs de validation / d'accès.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results