Port API module to D8 (#2648976) · Issues · project / api

Port API module to D8

>>> [!note] Migrated issue   Reported by: [nickdickinsonwilde](https://www.drupal.org/user/3094661) >>> <h3>Current development status <small>(March 10th, 2022)</small></h3> <p><strong>Full migration plan:</strong> <a href="https://docs.google.com/spreadsheets/d/e/2PACX-1vQGnqKKY0i0CVdBc5oBQ81BzetfAJtHluxzXrdfkGFahyRtI6vYTAmJwgTtxkRZDYLTbCSa5PHioear/pubhtml">Port "api" module to D9</a></p> <p><b><em>[Status] Milestone: Description</em></b><br> -----------------------------------------------</p> <ul> <li>[DONE] Backend: Set up all backend navigation and initial entities.</li> <li>[DONE] Parsing: Processing of the code (Parsing) as well as formatting of this.</li> <li>[DONE] Output: Front end navigation of all parsed entities.</li> <li>[DONE] Misc: Additional elements (blocks, comments), integrations (Search, SearchAPI...) and functional tests.</li> <li>Our next step is to plan the site migration for api.drupal.org, but that's actually out of the scope of the module porting.</li> </ul> <hr> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>This issue is a roadmap meta-issue for porting the API module to Drupal 8.x. The first 18 comments were about when/whether to port, at which point we made this into a Roadmap issue.</p> <h3 id="summary-proposed-resolution">Roadmap of Drupal 8 Port</h3> <p><strong>This is currently incomplete</strong></p> <h4>Configuration</h4> <p>The D7 configuration of this module consists of:</p> <ol> <li>Projects -- correspond to a Project on drupal.org, of type Core, Module, Theme <p>=> In Drupal 7, these are stored in database table api_branch.</p> <p>==> In Drupal 8, would be a Config Entity. </p></li> <li>Code Branches -- each Project can have one or more Branches, meaning information about a set of code that can be parsed, updated, and displayed on the site. Example: the 'drupal' project could have branches for 6.x, 7.x, 8.0.x, etc. You could also use them for released versions, such as 8.1.3. Each one has a separate area on the site for looking at the code/documentation. <p>=> In Drupal 7, these are stored in database table api_branch.</p> <p>==> In Drupal 8, would be a Config Entity. </p></li> <li>PHP reference branches -- information used to download signatures for base PHP functions from sites like php.net, which is used to make links in the documentation to base PHP functions (for example, in code, strpos() would turn into a link to php.net's documentation for the strpos function). <p>=> In Drupal 7, these are stored in database table api_php_branch.</p> <p>==> In Drupal 8, would be a Config Entity. </p></li> <li>API reference branches -- information used to download function signatures from api.drupal.org, for sites running the API module for a contrib module that don't want to also parse and maintain Drupal Core code. <p>=> In Drupal 7, these are stored in database table api_php_branch, along with the PHP reference branches.</p> <p>==> In Drupal 8, would be a Config Entity. Could be the same Config Entity as the PHP reference branches, or a separate one? </p></li> <li>Some configuration related to comments and fake nodes. (see separate section on comments).</li> <li>Some block configuration for the navigation block, that allows it to be hidden on certain types of API pages (see separate section on blocks)</li> <li>Miscellaneous variables (in Drupal 7, these are handled with variable get/set):<br> - api_do_cron -- set to TRUE if cron should be run. Defaults to 0, but when any API admin page is visited, is set to 1.<br> - api_default_branch -- the branch ID of the default branch. Visiting the main URL for the API part of the site will go to that branch.<br> - api_default_project -- Name of the default project to display if none is given in a URL.<br> - api_default_core_compatibility -- The core compatibility of the default branch/version to display if none is given in a URL.<br> - api_opensearch_name, api_opensearch_description -- Name and description of the site for OpenSearch<br> - api_breaks_where -- Characters to allow line breaks on in class/function names (mostly useful for wide tables)<br> - api_breaks_tag -- HTML entity or tag used to indicate line breaks in API pages<br> - api_reference_limit -- How many references to show on API pages before the link to see all (this is for "N functions call this" etc., and there is no UI for setting it, so it's effectively always 5 unless someone overrides it in settings.php) <p>==> In Drupal 8, we would probably put all of this into a Simple Configuration item (not a config entity, since there is only one of it, just a single YML file with schema and a settings form) (or could be split up into a few forms and/or a few YML files). </p></li> <li>The search integration sub-module also has some configuration (see separate section on that module)</li> </ol> <h4>Queues</h4> <p>In D7, the API module makes use of 3 queues that are defined in a hook_cron_queue_info() implementation:</p> <ol> <li>api_branch_update : Jobs in this queue update code branches, PHP reference branches, and API reference branches. For reference branches, "update" means the data is downloaded from the web and stored. For code branches, "update" means that the file system is checked against the list of the files in the branch and when they were last parsed. New files and files that have changed since their last parsed are added to the api_parse queue. Files that were previously in the branch but have been removed have their records removed, and then they're also added to the api_node_delete queue.</li> <li>api_parse : Jobs in this queue parse a single file from a single branch, and save the API items that are found in the database. Also, items that were previously found in this file but no longer are in the file are removed, and if so, jobs are added to the api_node_delete queue.</li> <li>api_node_delete : Jobs in this queue get rid of the fake nodes that correspond to API items that have been removed.</li> </ol> <p>===> In Drupal 8, the first two queues will need to be replicated. Information on the Drupal 8 queue API is here:<br> <a href="https://api.drupal.org/api/drupal/core%21core.api.php/group/queue/8.3.x">https://api.drupal.org/api/drupal/core%21core.api.php/group/queue/8.3.x</a><br> It's not clear to me that D8 queues work the same as D7 queues (automatically run during cron), so we'll need to look into that.</p> <p>The third queue would become an entity delete queue rather than node delete.</p> <h4>Parsing</h4> <p>(this is about the parsing of individual PHP files)<br> <strong>To Be Determined</strong> -- but probably similar to what is in D7, or exactly the same? Uses namespaced classes from 3rd-party library.</p> <h4>API item data storage</h4> <p>In Drupal 7, we stored API item information as follows:<br> - Each API item (such as a function, class, method, constant, topic, etc.) has an entry in the api_documentation table.<br> - Some API items have additional database entries, such as files (table api_file), functions (table api_function), namespace and use declarations (table api_namespace)<br> - Relationships between API items are stored in tables api_reference_storage, api_reference_counts, api_members, and api_overrides.<br> - Each API item also has a fake node associated with it. The Node ID is also the 'did' field in the api_documentation table.</p> <p>===> In Drupal 8, we should instead store this data in content entities. Most likely it would make sense to have separate entities for each type of API item, or else one entity type and having the API item types be bundles with "fields" for the data that is specific to some of the types and for the relationships:<br> - File<br> - Function (including class methods)<br> - Class<br> - Interface<br> - Trait<br> - Namespace<br> - Constant (including class constants)<br> - Global variable<br> - Class property<br> - Service (Drupal 8 services)<br> - Topic/group</p> <h4>API reference item data storage</h4> <p>(this is the data collected from PHP and API reference branches. In D7 stored in tables api_php_documentation and api_external_documentation)<br> <strong>To Be Determined</strong></p> <h4>API page output</h4> <p>(this is about taking the API data and making it into page output, including the listing views)<br> <strong>To Be Determined</strong></p> <h4>Comments</h4> <p>In D7, we made fake nodes for each API item, so that if the Comment module was enabled, you could comment on the pages.</p> <p>===> In D8, we should be able to allow commenting on the D8 content entities that store data for each API item. If possible, it would be good to have a centralized place to set up commenting on all API items, rather than having to attach a Comment field manually to each D8 content entity type.</p> <h4>Blocks</h4> <p>The API module provides 2 blocks:</p> <ol> <li>Search -- contains a search form with autocomplete, which lets you search for exact and partial text matches of names of classes, functions, etc.</li> <li>Navigation -- provides a list of links to lists of functions, classes, etc. in the currently-displayed branch, and has configuration for displaying this block only on certain types of API item pages</li> </ol> <p>===> In Drupal 8, these need to be converted from the D7 hook_block_* implementations to being block plugin classes.</p> <h4>Permissions</h4> <p>Two permissions:<br> - access API reference (see the page output)<br> - administer API reference (administration)</p> <p>===> In Drupal 8, these need to be converted to a permissions YML file instead of the D7 hook.</p> <h4>Miscellaneous functionality</h4> <p>- There's a text filter that will make links to API functions<br> - There are some hooks for other modules to use<br> - Drush commands<br> - Function dump URL<br> - Autocomplete URLs<br> <strong>To Be Determined</strong></p> <h4>Automated tests</h4> <p>We have a set of automated functional tests for Drupal 7, as well as a couple that probably fall into the category of unit testing.</p> <p>==> In Drupal 8, it would probably be a good idea to unit test some of the new classes... but we also need to definitely port the existing functional tests.</p> <h4>Migration</h4> <p>(this is about taking the API data from Drupal 7, including comments, and migrating it to Drupal 8)<br> <strong>To Be Determined</strong></p> <h4>Search integration sub-module</h4> <p>(There is a sub-module called api_search, which helps integrate with the core Search module and with Solr search. It also has some configuration. And tests. Also it will need to have migrate support I think.)<br> <strong>To Be Determined</strong></p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <p>Child issues to port various parts of this module to Drupal 8:<br> <strong>To Be Determined</strong></p> > Related issue: [Issue #2939599](https://www.drupal.org/node/2939599)

issue