5

So I'm using phpDocumentor 3 to generate documentation for my Laravel 7 project,

and was wondering if I could serve this documentation (static files) from Laravel in order to make it available only to authorized users.

I would like to be able to update the documentation through my CI/CD, so I can't just modify manually the generated documentation.

I think that I might have to write my own template (https://docs.phpdoc.org/3.0/guide/guides/templates.html) for that but I'm not sure whether the documentation is incomplete or if I'm missing something because I have no idea how to create a template. Any suggestions, guides or tutorials that can help me achieve this please ?
Thank you

hereForLearing
  • 1,209
  • 1
  • 15
  • 33

1 Answers1

1

You can include the phpDoc generation within your CI/CD script:

first install the phpDocumentor on the production, then generate using this command:

phpDocumentor -d . -t storage/docs/

Note: the storage path maybe is gitIgnored if you plan to generate the phpDocs, not on the production server, you have to be sure that the folder will be pushed to the production

add this to the config/filesystem.php 'disks':

'local-docs' => [
            'driver' => 'local',
            'root' => storage_path('docs'),
        ],

and add the following in your routes file (routes/web.php)

Route::get('/docs/{url?}', function ($url) {
    $resp = response(Storage::disk('local-docs')->get($url));
    $resp->header('content-type', GuzzleHttp\Psr7\MimeType::fromFilename($url));
    return $resp;

})->where('url', '(.*)')->middleware('auth');

be sure you haven't any other route with the docs prefix

Abilogos
  • 4,777
  • 2
  • 19
  • 39
  • 1
    Thank you so much for your answer, I didn't have the time to test it yet, once I do I will accept the answer and give you the bounty, thank you ! – hereForLearing Nov 30 '21 at 14:28
  • 1
    I've tested it ^^' It kind of work, but the css doesn't apply, I did a quick comparison and find out that despite of the css being downloaded it is not applied, I think it might have to do something with the missing response headers ? like on a normal page I have 'content-type: text/css' but on docs the css are returned as 'content-type: text/html', so I've added to your answer some headers and it's working now, thank you! – hereForLearing Nov 30 '21 at 15:01
  • 1
    `Route::get('/docs/{url?}', function ($url) { $resp = response(Storage::disk('local-docs')->get($url)); if(preg_match('/(.*.css)/', $url)) $resp->header('content-type', 'text/css'); else if(preg_match('/(.*.js)/', $url)) $resp->header('content-type', 'application/javascript'); return $resp; })->where('url', '(.*)');` – hereForLearing Nov 30 '21 at 15:01
  • 1
    the main types that may impact the docs are javsacript/css so I didn't cover the rest of the cases, but I'm sure there is a better way to do that, if you can update your answer with my code (or a better solution) it would be great, thank you ! – hereForLearing Nov 30 '21 at 15:03
  • 1
    @hereForLearning thanks, I have updated my answer with your mime-type correction. I am glad that your problem has resolved – Abilogos Nov 30 '21 at 15:13
  • 1
    ok last update (I hope ^^'): we can get the MimeType from the extension without the if/else as follow : $resp->header('content-type', GuzzleHttp\Psr7\MimeType::fromFilename($url)); – hereForLearing Nov 30 '21 at 15:23
  • 1
    awesome :+1 it looks better now. thanks @hereForLearning . I have searched for it, but I couldnt found your solution :+1 – Abilogos Nov 30 '21 at 15:26