yamf php

Yamf

YAMF (encore un autre framework MVC) est un petit framework MVC PHP conçu pour vous permettre d'utiliser rapidement le paradigme MVC sans beaucoup de travail de configuration. Tout ce dont vous avez besoin est un serveur Web qui accepte les fichiers .htaccess et vous êtes à peu près bon à partir!

Installation

Exigences minimales: PHP 7.0+.

1. Clone le référentiel et / ou utilisez ce projet comme modèle pour votre propre projet en cliquant sur ce lien ou en cliquant sur le bouton Use this template sur la page Repo du projet principal.
2. Assurez-vous que votre serveur Web est configuré pour lire et utiliser des fichiers .htaccess. (Si vous ne savez pas ce que cela signifie, veuillez le Google!
3. Configurez config.php si nécessaire. Ajustez tous les paramètres que vous souhaitez là-bas ou ajoutez de nouveaux paramètres à $app , tels que la logique de session. Par défaut, vous n'avez pas besoin de régler quoi que ce soit pour mettre votre site opérationnel.
4. Si vous avez des informations d'identification de base de données, des clés privées, etc. qui doivent être utilisées dans le site Web, copiez config-private.sample.php à config-private.php et ajustez-la à vos besoins. Par exemple, vous pouvez configurer $app->db pour être une instance PDO pour votre base de données locale. Notez que config-private.php sera chargé avant que tout dans config.php ait lieu.
5. Pour que les instructions use Yamf/XYZ fonctionnent, vous devrez utiliser Composer. Utiliser le compositeur est assez facile: accédez à la page de téléchargement et exécutez le script en haut. (Remarque: si vous êtes sous Windows, vous voudrez suivre les instructions ici sur la page d'introduction.)
6. composer install (si vous avez un fichier composer.phar dans votre répertoire, exécutez php composer.phar install ). Il s'asseoira et réfléchira une minute.
7. Vous avez terminé! Profitez de votre site Web basé sur MVC! Vous pouvez arracher les exemples d'éléments par défaut et CSS, bien sûr!

Attendez! Où se trouve la bibliothèque de migration de la base de données / vue de la bibliothèque de tests de modèles / un unité de bibliothèque / {autre framework ici} ?!

Ils ne sont pas là, et ils ne sont pas là exprès! YAMF a été délibérément écrit pour ne pas utiliser de dépendances externes autres que l'autoader du compositeur pour abaisser la barrière d'entrée à l'utilisation du paradigme MVC en PHP. Si vous voulez l'une de ces choses, tirez-les simplement avec votre gestionnaire de dépendance préféré (comme compositeur). Étant donné que le compositeur est déjà nécessaire pour exécuter ce projet pour la mise à jour PSR-4, nous vous recommandons d'utiliser Composer. vendor/autoload.php est déjà inclus pour vous dans init.php .

Pour une note concernant les modèles de vue, consultez la section sur la sous-classe.

Documentation

Si vous lisez la documentation suivante sur YAMF, vous serez probablement bien mieux que de simplement sauter et d'essayer de lire le code vous-même. :) Cela ne prendra que quelques minutes, et cela en vaut la peine!

Remarques sur l'application $

Afin de faciliter le passage facile des paramètres de configuration, tels que les paramètres de base de données, etc., YAMF transmet une variable $app de la classe YamfAppConfig à chaque fonction de contrôleur. Vous pouvez configurer cette variable pour stocker votre objet PDO de la base de données, modifier votre extension de vue ou votre emplacement de dossier et de nombreux autres paramètres. Si vous souhaitez ajouter vos propres valeurs à $app , vous pouvez créer une classe qui dérive de YamfAppConfig et modifier le paramètre appConfigClass dans config.php pour pointer vers votre classe personnalisée. Notez que votre classe personnalisée doit dériver de YamfAppConfig ! Voir config.php pour voir tous les paramètres et valeurs qui sont passés par YAMF via $app . Notamment, vous pouvez:

• Modifiez l'emplacement de votre dossier de vues ( viewsFolderName )
• Modifiez l'extension de vos fichiers de vue ( viewExtension )
• Modifiez le nom de l'en-tête ou du pied de page par défaut ( defaultHeaderName / defaultFooterName )
• Ayez un accès facile à votre base de données PDO / autre (configurer dans config-private.php )

$app est automatiquement disponible dans vos vues pour vous.

Ajouter un nouvel itinéraire

La première chose que vous voudrez probablement faire est d'ajouter un nouvel itinéraire. Pour ce faire, suivez ces étapes:

1. Si vous n'avez pas déjà de classe de contrôleur pour votre nouvel itinéraire, allez-y et ajoutez-en un dans le dossier app/Controllers du projet. Les sous-dossiers sont OK. Le contrôleur n'a pas vraiment besoin d'avoir Controller dans le nom, mais assurez-vous que le nom de classe correspond au nom du fichier.
2. Ajoutez un talon pour votre méthode de contrôleur. À tout le moins, ce doit être une fonction public qui prend deux paramètres: $app et $request (dans cet ordre).
3. Ouvrez routes.php et assurez-vous de comprendre la documentation et les exemples du fonctionnement des routes.
4. Ajoutez votre itinéraire au tableau routes .
   • Assurez-vous de désigner POST si nécessaire.
   • La chaîne de nom du contrôleur doit correspondre au nom de fichier et au nom de classe du contrôleur à partir de la première étape.
   • Si le contrôleur est dans un sous-dossier (ou sous-dossiers), assurez-vous d'avoir le nom au format Parent-Folder/Controller-Name .
   • Le nom de la fonction doit correspondre au nom de la fonction de l'étape 2.
5. À ce stade, l'itinéraire fonctionne, mais votre méthode de contrôleur doit renvoyer une sorte de yamf/Responses/Response , qui peut être de la View à une réponse JSON à, eh bien, tout ce que vous voulez, vraiment. Voir la section suivante pour plus d'informations ici.
6. Votre cas d'utilisation normal renvoie probablement un yamf/Responses/View . Créer un fichier PHP (voir) dans le dossier views - encore une fois, les sous-dossiers sont OK - et, dans votre méthode de contrôleur, return new View('name/of/view'); .
7. L'itinéraire devrait maintenant être fonctionnel!

En bref:

1. Ajouter la méthode du contrôleur et du contrôleur au dossier app/Controllers
2. Ajouter un itinéraire vers routes.php
3. Créer une vue dans le dossier views si nécessaire
4. Modifier la méthode du contrôleur pour return new View('name/of/view');

Types de retour des fonctions du contrôleur

Toutes les méthodes de contrôleur appelées à la suite d'un itinéraire doivent renvoyer un yamf/Responses/Response ou une sous-classe de ladite classe. Voici quelques descriptions sur la façon d'utiliser chacun. La plupart peuvent être utilisés en une seule ligne avec juste le constructeur.

• Response - La classe de base pour une réponse d'un itinéraire.
  • Format du constructeur: new Response($statusCode = 200)
  • Sorte le code d'état.
  • Étant donné que tous les autres éléments yamf/Responses/Response sous-classent de cette classe parent, ils peuvent tous renvoyer un code d'état HTTP personnalisé, si vous le souhaitez!
• ErrorMessage - simple enveloppe autour de la vue pour renvoyer un code d'état 400 et la vue error.php.
  • Format du constructeur: new ErrorMessage($msg = '', $name = 'error', $title = '', $headerName = '', $footerName = '') . $name est le nom de la vue.
  • Notez que le premier paramètre est le message d'erreur, pas le nom de la vue!
  • Par défaut, le nom de variable pour l'erreur à sortir dans votre vue est $error . Vous ne pouvez pas changer cela sans sous-classe.
  • Par défaut, l'en-tête et le pied de page utilisé sont views/header.php et views/footer.php .
  • Le code d'état peut bien sûr être modifié.
• JsonResponse - Exemple sur la façon dont vous pouvez renvoyer une réponse JSON de votre contrôleur
  • Format du constructeur: new JsonResponse($data, $jsonEncodeOptions = 0)
  • Sorties $data via echo json_encode($this->data, $this->jsonEncodeOptions);
• NotFound - Utilisé pour retourner un message 404 non trouvé au client.
  • Format du constructeur: new NotFound($name = '404', $data = [], $title = '', $headerName = '', $footerName = '') . $name est le nom de la vue.
  • Par défaut, l'en-tête et le pied de page utilisé sont views/header.php et views/footer.php .
  • Si vous souhaitez renvoyer un 404 (par exemple pour une API), utilisez Response .
• Redirect - Permet une redirection 302 vers une autre page ou un autre itinéraire
  • Format du constructeur: new Redirect($redirectPath, $isInternalRedirect = true)
  • Le code d'état est 302 par défaut
  • $isInternalRedirect est utilisé pour rediriger vers un itinéraire dans les données actuelles du site Web / routes.php . Si vous souhaitez rediriger vers un itinéraire interne, utilisez Redirect comme celle-ci: new Redirect('/route/name); (Notez le démarrage / ). Sinon, utilisez Redirect comme ceci: new Redirect('https://example.com', false); .
• View - Utilisé pour retourner une vue HTML basée sur PHP.
  • Format du constructeur: new View($name, $data = [], $title = '', $headerName = '', $footerName = '') . $name est le nom de la vue.
  • Pour envoyer des données à votre avis, le moyen le plus simple est probablement d'utiliser la fonction compact . Voir le BlogController de l'échantillon.
  • Par défaut, l'en-tête et le pied de page utilisé sont views/header.php et views/footer.php .

Si vous avez des idées pour plus de types Response qui devraient être inclus dans YAMF, veuillez ouvrir une demande de fonctionnalité (via l'onglet Issues) ou ouvrir une demande de traction!

Données envoyées dans les méthodes du contrôleur

Deux variables principales sont envoyées dans vos méthodes de contrôleur à partir de l'itinéraire: $app et $request . Notez que toutes les sorties View auront les variables $app et $request disponibles à utiliser. Vous n'avez pas besoin de les envoyer sous forme de paramètre $data .

AppConfig $app

$app est principalement des variables de configuration que vous avez configurées dans config.php . Vérifiez ce fichier pour un coup d'œil rapide sur ce qui est disponible. Certains des éléments les plus importants sont:

• $app->db pour une connexion de base de données
• Noms de fichiers d'en-tête par défaut pour toutes les vues, la page 404 et la page d'erreur. Vous pouvez les définir sur null pour éviter de les utiliser du tout.

En plus de ceux-ci, deux variables sont disponibles qui sont configurées dans init.php :

• $app->isLocalHost - Que l'application s'exécute ou non sur l'hôte local ( 127.0.0.1 ou ::1 )
• $app->basePath - Le répertoire de base de votre application Web actuelle. Cela peut être utilisé pour permettre des applications Web imbriquées sur votre serveur Web. Je recommande fortement d'utiliser cette variable dans vos views lorsque vous faites des liens de site Web local afin que si vous déplacez des fichiers ou déplacez les choses ultérieures dans un sous-dossier, tout ne se casse pas. Pour créer un lien vers une autre page de votre site, utilisez simplement la fonction $app->yurl(string) (yamf URL) comme ceci: <?= $app->yurl('/path/to/page') ?> .

$request

$request va avoir toutes vos données sur votre itinéraire et les différents paramètres qui sont venus avec votre demande. Il est de type yamf/Request . Il a ces membres publics disponibles:

• $request->route - chaîne de route brute pour cette demande
• $request->controller - Nom de la chaîne du contrôleur
• $request->function - Nom de la chaîne de la fonction du contrôleur à appeler
• $request->routeParams - tous les paramètres de l'itinéraire tels que {id}. Format: ['id' => valeur]
• $request->get - tout se passer par les paramètres dans l'URL - même format que $ _get (pas de traitement supplémentaire effectué)
• $request->post - tout params de post - même format que $ _post (pas de traitement supplémentaire effectué)
• $request->anchor - Si utilisé, la partie # de l'URL (sans le #). Le routeur est assez intelligent pour ne pas correspondre aux URL comme /blah/#/foo .

Sous-classement pour prolonger le cadre

La façon la plus simple pour vous d'étendre ce cadre est de dériver de Response (ou d'une autre classe d'enfants Response ) et / ou de créer une classe de parents pour certains de vos contrôleurs. Par exemple, en dérivant de View , vous pouvez modifier la sortie de la vue pour utiliser le moteur de modèles de brindilles au lieu de la sortie PHP simple. En créant une classe parent pour vos contrôleurs, vous pouvez ajouter des choses comme la validation ou d'autres traitements supplémentaires des données qui doivent se produire pour toutes vos itinéraires API, tels que la vérification d'un nom d'utilisateur / mot de passe ou jeton. Les options sont infinies et le potentiel génial!

Il y a un exemple d'utilisation de la brindille au lieu de PHP brut sur la branche brindille!

Simplicité de page statique

Une fonctionnalité Nifty que YAMF prend en charge est les pages Web statiques qui ne nécessitent pas de route ou de controller . Si vous voulez /about d'être une page simple, lancez une page about.php dans les views/static/ dossier et - bam! - /about des travaux sur votre site Web. Qu'en est-il des sous-dossiers comme /blog/post-name ? Cela fonctionne aussi! Ajoutez un fichier views/static/blog/post-name.php et cela fonctionne simplement (TM)! Vous pouvez l'utiliser pour avoir encore de jolies URL sur votre site Web sans vous soucier d'ajouter des itinéraires et des contrôleurs.

Vous pouvez configurer l'emplacement des vues statiques dans config.php .

Notez que le routeur tente de faire correspondre une route router.php avant de vérifier les pages statiques.

Raccourcissement URL

Une fonctionnalité que le routeur prend en charge qui n'est pas immédiatement activée est le raccourcissement de l'URL - par exemple https://example.com/short-url . Il nécessite une connexion de base de données, mais si vous ajoutez la connexion de la base de données et que vous avez la table de base de données appropriée (le schéma est dans config.sample.php ), le raccourcissement de l'URL peut être utilisé si vous le souhaitez. Vous n'êtes pas obligé d'activer cette fonctionnalité.

Logique de session par défaut

J'ai inclus une logique de session par défaut commentée dans config.sample.php . N'hésitez pas à l'utiliser, à le modifier ou à le jeter. Si vous avez des suggestions sur la façon d'améliorer cette fonctionnalité, veuillez ouvrir une demande de traction ou un problème pour générer une discussion supplémentaire.

Puis-je aider à contribuer?

Heureux que vous ayez demandé! Il y a toujours des choses qui peuvent être faites sur un projet open source: corriger les bogues, les nouvelles fonctionnalités, et plus encore! Consultez l'onglet Issues de ce référentiel et jetez un œil aux bogues signalés et quelles fonctionnalités ont été demandées. Il y a plus d'informations sur la contribution du document contribuant.

Licence

Licence MIT. Veuillez vous assurer d'inclure la licence pour ce cadre (avec un lien GitHub si vous vous sentez généreux!) Lorsque vous l'utilisez sur votre site. Merci! :)

Merci spécial

Un merci spécial à BootSwatch pour le thème papier bootstrap utilisé dans l'échantillon.