Support for Helper Functions?

[onairmarc]

Looking through the code and searching online, I do not see a way to include helper functions that are added to the autoload.files key in composer.json. If I'm missing it, can someone please point this out to me? If I'm not missing it, can this be added?

[williamdes]

Hello !

Can you share your configuration file ? Helper files should be added to the discovery for them to be documented

[onairmarc]

Sure thing! Here it is:

<?php

/*
 * Copyright (c) 2024. Encore Digital Group.
 * All Right Reserved.
 */

use Doctum\Doctum;
use Symfony\Component\Finder\Finder;

$iterator = Finder::create()
    ->files()
    ->notName('Kernel.php')
    ->name('*.php')
    ->in([
        'app',
        'app_modules',
        'vendor/encoredigitalgroup',
        'vendor/filament',
        'vendor/laravel/framework/src/Illuminate',
    ])
    ->exclude([
        '_EncoreDigitalGroup',
        'vendor/encoredigitalgroup/modular/stubs',
    ]);

return new Doctum($iterator, [
    'title' => 'MyPortal.Church API',
    'language' => 'en', // Could be 'fr'
    'build_dir' => __DIR__ . '/storage/doctum_docs/build',
    'cache_dir' => __DIR__ . '/storage/doctum_docs/cache',
    'default_opened_level' => 0,
    'theme' => 'custom',
    'template_dirs' => [__DIR__ . '/resources/doctum/themes/custom'],
]);

[onairmarc]

Helper files are already co-located with the directories.

[williamdes]

Thank you for the config.

Helper files are already co-located with the directories.

Can you print a tree so I can better understand where are the files and their extension ?

[onairmarc]

Here's a screenshot of one of the internal packages I have Doctum pointed at in the project. All of the Class files appear as expected, but the functions in the helpers.php file do not appear.

[williamdes]

Okay, It seems I will have to ask you to dump $iterator and check the file is included. And if it is, then maybe share your helpers.php file (function contents not needed)

[onairmarc]

I'll try to get to this later this afternoon. Thanks!

[onairmarc]

This is from adding var_dump($iterator) to the docutm config file immediately after $iterator. From what I can see, the directory correct vendor directory, encoredigitalgroup is included in the $iterator but the helpers.php file is not included.

Iterator

object(Symfony\Component\Finder\Finder)#115 (19) {
  ["mode":"Symfony\Component\Finder\Finder":private]=>
  int(1)
  ["names":"Symfony\Component\Finder\Finder":private]=>
  array(1) {
    [0]=>
    string(5) "*.php"
  }
  ["notNames":"Symfony\Component\Finder\Finder":private]=>
  array(1) {
    [0]=>
    string(10) "Kernel.php"
  }
  ["exclude":"Symfony\Component\Finder\Finder":private]=>
  array(2) {
    [0]=>
    string(5) "stubs"
    [1]=>
    string(5) "tests"
  }
  ["filters":"Symfony\Component\Finder\Finder":private]=>
  array(0) {
  }
  ["depths":"Symfony\Component\Finder\Finder":private]=>
  array(0) {
  }
  ["sizes":"Symfony\Component\Finder\Finder":private]=>
  array(0) {
  }
  ["followLinks":"Symfony\Component\Finder\Finder":private]=>
  bool(false)
  ["reverseSorting":"Symfony\Component\Finder\Finder":private]=>
  bool(false)
  ["sort":"Symfony\Component\Finder\Finder":private]=>
  bool(false)
  ["ignore":"Symfony\Component\Finder\Finder":private]=>
  int(3)
  ["dirs":"Symfony\Component\Finder\Finder":private]=>
  array(4) {
    [0]=>
    string(3) "src"
    [1]=>
    string(25) "vendor/encoredigitalgroup"
    [2]=>
    string(15) "vendor/filament"
    [3]=>
    string(39) "vendor/laravel/framework/src/Illuminate"
  }
  ["dates":"Symfony\Component\Finder\Finder":private]=>
  array(0) {
  }
  ["iterators":"Symfony\Component\Finder\Finder":private]=>
  array(0) {
  }
  ["contains":"Symfony\Component\Finder\Finder":private]=>
  array(0) {
  }
  ["notContains":"Symfony\Component\Finder\Finder":private]=>
  array(0) {
  }
  ["paths":"Symfony\Component\Finder\Finder":private]=>
  array(0) {
  }
  ["notPaths":"Symfony\Component\Finder\Finder":private]=>
  array(0) {
  }
  ["ignoreUnreadableDirs":"Symfony\Component\Finder\Finder":private]=>
  bool(false)
}

Helpers File

<?php

/*
 * Copyright (c) 2023-2024. Encore Digital Group.
 * All Rights Reserved.
 */

use EncoreDigitalGroup\Common\Helpers\Objectify;
use JShrink\Minifier;

if (! function_exists('minify')) {
    /**
     * @throws Exception
     */
    function minify(string $content): bool|string
    {
        return Minifier::minify($content);
    }
}

if (! function_exists('objectify')) {
    function objectify($array): stdClass|array
    {
        return Objectify::me(array: $array);
    }
}

if (! function_exists('notNull')) {
    function notNull($value): bool
    {
        return not_null($value); //Yes, we are writing a helper function for a helper function. Refactors are fun...
    }
}

This is one of several different helper files across multiple different internal packages. I'm starting with the smallest one and working my way up from there.

[onairmarc]

@williamdes Just checking in on this.

[williamdes]

Hi @onairmarc

From what I can see, the directory correct vendor directory, encoredigitalgroup is included in the $iterator but the helpers.php file is not included.

You really need to check the file helpers.php is included :) Maybe a foreach of each file item ? Our test suite show that helper functions are supported and work: https://github.com/code-lts/doctum/blob/main/tests/phar/data/src/functions.php

[onairmarc]

@williamdes On my to-do list! Will report back. 🤓

[onairmarc]

@williamdes Sorry for the delay. It looks like several helpers.php are included from the /vendors directory but are not included from the /src directory. Technically this is half way to where I want to be. I still need all of the different helper files from /src to be included.

Here's a sample of the output where helpers were included:

  [4451]=>
  object(Symfony\Component\Finder\SplFileInfo)#4603 (4) {
    ["relativePath":"Symfony\Component\Finder\SplFileInfo":private]=>
    string(11) "Collections"
    ["relativePathname":"Symfony\Component\Finder\SplFileInfo":private]=>
    string(23) "Collections/helpers.php"
    ["pathName":"SplFileInfo":private]=>
    string(63) "vendor/laravel/framework/src/Illuminate/Collections/helpers.php"
    ["fileName":"SplFileInfo":private]=>
    string(11) "helpers.php"
  }