How jikan-me/jikan works
Project Type and Purpose
• Jikan is a PHP library and API that scrapes MyAnimeList’s website to provide an unofficial API. Its purpose is to abstract the complexities of web scraping and parsing by offering easy-to-use classes to fetch and convert MyAnimeList data into PHP objects.
• This project primarily serves as a backend library, with its consumers being other applications (or even a REST API built on top of it) needing MAL data.
Key Components
• API Client & Request Manager:
• HTTP client layer. Highlight the “src/MyAnimeList/MalClient.php” as the central API client that issues HTTP requests.
• “src/Request” folder which is subdivided into multiple domains (Anime, Manga, Character, etc.). Each Request class (for example, AnimeRequest, MangaRequest, etc.) encapsulates how to call specific endpoints on MyAnimeList via scraping.
• Parsing Layer:
• “src/Parser” directory, which is organized into multiple subdirectories (Anime, Manga, Character, Forum, etc.). Each parser (e.g., AnimeParser, MangaParser, etc.) takes raw HTML or response data received from MyAnimeList and converts it into structured data.
• A directional flow from the Request layer to the Parser layer.
• Data Model Layer:
• “src/Model” directory. These components (like Anime, Manga, Character entities, etc.) represent the domain-specific objects that the API returns.
• That Models are the outcome of the data processed by their corresponding Parsers.
• Utility and Helper Components:
• Elements from “src/Helper” (such as Constants, Media, Parser, etc.), which provide shared utilities and common functionality across the library.
• Exception Handling:
• “src/Exception” components for managing errors (e.g., BadResponseException, ParserException).
• Third-Party Integration:
• “src/Goutte” folder (containing GoutteWrapper) to highlight its role in web scraping. This shows that Jikan leverages the Goutte library (a PHP web scraping library) to retrieve HTML data from MyAnimeList.
• Testing & Quality Assurance:
Architectural Relationships and Interaction Flow
• The consumer calls the API Client (MalClient), which then constructs a specific Request (e.g., AnimeRequest) based on the domain data needed.
• The Request component performs an HTTP call via GoutteWrapper, fetching raw HTML from MyAnimeList.
• Fetched HTML is passed to the appropriate Parser (e.g., AnimeParser, MangaParser) which extracts and structures the data.
• The Parser then instantiates and populates a Model object (for example, an Anime model) representing the data.
• Any errors encountered are thrown as Exceptions (BadResponseException, ParserException) and handled accordingly.
• Optionally, note the use of Helper utilities for common operations and constants that drive consistent behavior across components.
Design Principles and Patterns
• Layered Architecture: Clearly segment the Request, Parser, Model, and Utility layers.
• Separation of Concerns: Each directory and set of files (like Request, Parser, and Model) is responsible for a distinct aspect of the data flow.
• Modularity: The organized subdirectories (Anime, Manga, Character, etc.) show domain-driven structures that are independently extendable.
• Error Handling: Centralize error management with dedicated Exception classes.