From d1913b09c3ee5869401eb2f695de14f170fd6e01 Mon Sep 17 00:00:00 2001 From: Steve Boyd Date: Thu, 28 Nov 2024 11:25:54 +1300 Subject: [PATCH] API Reorganise file structure --- README.md | 177 +---------------- _config/securityreport.yml | 2 +- _config/sitewidecontent-report.yml | 4 +- .../MemberReportExtension.php | 2 +- .../{ => Reports}/UserSecurityReport.php | 2 +- .../SitewideContentTaxonomy.php | 6 +- .../{ => Reports}/SitewideContentReport.php | 2 +- docs/en/index.md | 186 ++++++++++++++++++ .../MemberReportExtensionTest.php | 4 +- .../MemberReportExtensionTest.yml | 0 .../{ => Reports}/UserSecurityReportTest.php | 6 +- .../{ => Reports}/UserSecurityReportTest.yml | 0 .../SitewideContentReportTest.php | 6 +- .../SitewideContentReportTest.yml | 0 14 files changed, 206 insertions(+), 191 deletions(-) rename code/SecurityReport/{ => Extensions}/MemberReportExtension.php (98%) rename code/SecurityReport/{ => Reports}/UserSecurityReport.php (98%) rename code/SiteWideContentReport/{Model => Extensions}/SitewideContentTaxonomy.php (92%) rename code/SiteWideContentReport/{ => Reports}/SitewideContentReport.php (99%) create mode 100644 docs/en/index.md rename tests/php/SecurityReport/{ => Extensions}/MemberReportExtensionTest.php (87%) rename tests/php/SecurityReport/{ => Extensions}/MemberReportExtensionTest.yml (100%) rename tests/php/SecurityReport/{ => Reports}/UserSecurityReportTest.php (93%) rename tests/php/SecurityReport/{ => Reports}/UserSecurityReportTest.yml (100%) rename tests/php/SiteWideContentReport/{ => Reports}/SitewideContentReportTest.php (94%) rename tests/php/SiteWideContentReport/{ => Reports}/SitewideContentReportTest.yml (100%) diff --git a/README.md b/README.md index 8979980b..2a0e2472 100644 --- a/README.md +++ b/README.md @@ -36,182 +36,9 @@ SilverStripe\Reports\Report: ``` Note that some reports may have overridden the `getCount` method, and for those reports this may not apply. -## Site-wide content report - -### Customising the report - -In order to customise the columns included in a report you can build a custom extension and apply it to the -SitewideContentReport as necessary. - -The built in `SitewideContentTaxonomy` extension, for instance, adds a custom columns extracted from the `silverstripe/taxonomy` modules, and can be used as a base for developing further extensions: - -For instance, in order to add a new Page field to the report you could add an extension similar to the below: - -```php - use SilverStripe\Core\Extension; - use SilverStripe\Reports\SiteWideContentReport\SiteWideContentReport; - - class MyReportExtension extends Extension { - protected function updateColumns($itemType, &$columns) { - if($itemType !== 'Pages') { - return; - } - $columns["Price"] = [ - "title" => _t(SitewideContentReport::class . ".Price", "Price"), - "formatting" => function ($value, $item) use ($mainSiteLabel) { - return number_format($value, 2, '.', ','); - }, - ]; - } - } -``` - -The `$columns` array can have any number of items added, where the key of the array represents the -field name to be included. - -Each item can be either a literal string (which will be used as the title), or an array that may contain -the following key => value pairs: - - * `title`: The title to use for the column header - * `format`: A method callback which will take the raw value and original object, and return a formatted - string. - * `datasource`: If the value for this column isn't a direct field on the original object, a custom callback - can be set here. Unlike `format` this callback will only take a single parameter, the original object. - * `printonly`: Set to true if this column is only visible on the print or export-to-csv views. - * `casting`: Specify a field type (e.g. `Text` or `Int`) in order to assist with field casting. This is not - necessary if `formatting` is used. - -### Performance considerations - -#### Large data sets - -If your project has a large number of pages or files, you may experience server timeouts while trying to export -this report to CSV. To avoid this issue, you can either increase your server timeout limit, or you can install -and configure the [silverstripe/gridfieldqueuedexport module](https://github.com/silverstripe/silverstripe-gridfieldqueuedexport) -which allows for CSV generation to offloaded to a queued job in the background. - -An example of configuring this module in your project: - -```php -use SilverStripe\Core\Extension; -use SilverStripe\Forms\GridField\GridFieldComponent; -use SilverStripe\GridfieldQueuedExport\Forms\GridFieldQueuedExportButton; - -class SitewideContentReportQueuedExportExtension extends Extension -{ - protected function updateExportButton(GridFieldComponent &$exportButton) - { - $exportButton = new GridFieldQueuedExportButton('buttons-after-left'); - } -} -``` - -Apply the example Extension above with YAML configuration in your project: - -```yaml ---- -Name: queuedsitewidecontentreport ---- -SilverStripe\Reports\SitewideContentReport\SitewideContentReport: - extensions: - - SitewideContentReportQueuedExportExtension -``` - -## External broken links report - -### Features - -* Add external links to broken links reports -* Add a task to track external broken links - -### Report - -A new report is added called 'External Broken links report'. When viewing this report, a user may press -the "Create new report" button which will trigger an ajax request to initiate a report run. - -In this initial ajax request this module will do one of two things, depending on which modules are included: - -* If the queuedjobs module is installed, a new queued job will be initiated. The queuedjobs module will then - manage the progress of the task. -* If the queuedjobs module is absent, then the controller will fallback to running a buildtask in the background. - This is less robust, as a failure or error during this process will abort the run. - -In either case, the background task will loop over every page in the system, inspecting all external urls and -checking the status code returned by requesting each one. If a URL returns a response code that is considered -"broken" (defined as < 200 or > 302) then the `ss-broken` css class will be assigned to that url, and -a line item will be added to the report. If a previously broken link has been corrected or fixed, then -this class is removed. - -In the actual report generated the user can click on any broken link item to either view the link in their browser, -or edit the containing page in the CMS. +## Included reports -While a report is running the current status of this report will be displayed on the report details page, along -with the status. The user may leave this page and return to it later to view the ongoing status of this report. - -Any subsequent report may not be generated until a prior report has completed. - -### Dev task - -Run `sake tasks:CheckExternalLinksTask` to check your site for external -broken links. - -### Queued job - -If you have the queuedjobs module installed you can set the task to be run every so often. - -### Whitelisting codes - -If you want to ignore or whitelist certain HTTP codes this can be setup via `ignore_codes` in the config.yml -file in `mysite/_config`: - -```yml -SilverStripe\Reports\ExternalLinks\Tasks\CheckExternalLinksTask: - ignore_codes: - - 401 - - 403 - - 501 -``` - -### Follow 301 redirects - -You may want to follow a redirected URL a example of this would be redirecting from http to https -can give you a false poitive as the http code of 301 will be returned which will be classed -as a working link. - -To allow redirects to be followed setup the following config in your config.yml - -```yaml -# Follow 301 redirects -SilverStripe\Reports\ExternalLinks\Tasks\CurlLinkChecker: - follow_location: 1 -``` - -### Bypass cache - -By default the task will attempt to cache any results the cache can be bypassed with the -following config in config.yml. - -```yaml -# Bypass SS_Cache -SilverStripe\Reports\ExternalLinks\Tasks\CurlLinkChecker:: - bypass_cache: 1 -``` - -### Headers - -You may want to set headers to be sent with the CURL request (eg: user-agent) to avoid website rejecting the request thinking it is a bot. -You can set them with the following config in config.yml. - -```yaml -# Headers -SilverStripe\Reports\ExternalLinks\Tasks\CurlLinkChecker: - headers: - - 'user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:53.0) Gecko/20100101 Firefox/53.0' - - 'accept-encoding: gzip, deflate, br' - - 'referer: https://www.domain.com/' - - 'sec-fetch-mode: navigate' - ... -``` +This module comes with a few customisable reports out of the box. Details on how to customise these reports can be found in the [documentation] section(./docs/en/index.md). ## Links ## diff --git a/_config/securityreport.yml b/_config/securityreport.yml index 384011b4..5ee58692 100644 --- a/_config/securityreport.yml +++ b/_config/securityreport.yml @@ -3,4 +3,4 @@ Name: reports-securityreportconfig --- SilverStripe\Security\Member: extensions: - - SilverStripe\Reports\SecurityReport\MemberReportExtension + - SilverStripe\Reports\SecurityReport\Extensions\MemberReportExtension diff --git a/_config/sitewidecontent-report.yml b/_config/sitewidecontent-report.yml index 1c082c06..e763ff10 100644 --- a/_config/sitewidecontent-report.yml +++ b/_config/sitewidecontent-report.yml @@ -3,6 +3,6 @@ Name: reports-sitewidecontenttaxonomy Only: moduleexists: silverstripe/taxonomy --- -SilverStripe\Reports\SiteWideContentReport\SitewideContentReport: +SilverStripe\Reports\SitewideContentReport\Reports\SitewideContentReport: extensions: - - SilverStripe\Reports\SiteWideContentReport\Model\SitewideContentTaxonomy + - SilverStripe\Reports\SiteWideContentReport\Extensions\SitewideContentTaxonomy diff --git a/code/SecurityReport/MemberReportExtension.php b/code/SecurityReport/Extensions/MemberReportExtension.php similarity index 98% rename from code/SecurityReport/MemberReportExtension.php rename to code/SecurityReport/Extensions/MemberReportExtension.php index d396fb91..623c282d 100644 --- a/code/SecurityReport/MemberReportExtension.php +++ b/code/SecurityReport/Extensions/MemberReportExtension.php @@ -1,6 +1,6 @@ 302) then the `ss-broken` css class will be assigned to that url, and +a line item will be added to the report. If a previously broken link has been corrected or fixed, then +this class is removed. + +In the actual report generated the user can click on any broken link item to either view the link in their browser, +or edit the containing page in the CMS. + +While a report is running the current status of this report will be displayed on the report details page, along +with the status. The user may leave this page and return to it later to view the ongoing status of this report. + +Any subsequent report may not be generated until a prior report has completed. + +### Dev task + +Run `sake tasks:CheckExternalLinksTask` to check your site for external +broken links. + +### Queued job + +If you have the queuedjobs module installed you can set the task to be run every so often. + +### Whitelisting codes + +If you want to ignore or whitelist certain HTTP codes this can be setup via `ignore_codes` in the config.yml +file in `mysite/_config`: + +```yml +SilverStripe\Reports\ExternalLinks\Tasks\CheckExternalLinksTask: + ignore_codes: + - 401 + - 403 + - 501 +``` + +### Follow 301 redirects + +You may want to follow a redirected URL a example of this would be redirecting from http to https +can give you a false poitive as the http code of 301 will be returned which will be classed +as a working link. + +To allow redirects to be followed setup the following config in your config.yml + +```yaml +# Follow 301 redirects +SilverStripe\Reports\ExternalLinks\Tasks\CurlLinkChecker: + follow_location: 1 +``` + +### Bypass cache + +By default the task will attempt to cache any results the cache can be bypassed with the +following config in config.yml. + +```yaml +# Bypass SS_Cache +SilverStripe\Reports\ExternalLinks\Tasks\CurlLinkChecker:: + bypass_cache: 1 +``` + +### Headers + +You may want to set headers to be sent with the CURL request (eg: user-agent) to avoid website rejecting the request thinking it is a bot. +You can set them with the following config in config.yml. + +```yaml +# Headers +SilverStripe\Reports\ExternalLinks\Tasks\CurlLinkChecker: + headers: + - 'user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:53.0) Gecko/20100101 Firefox/53.0' + - 'accept-encoding: gzip, deflate, br' + - 'referer: https://www.domain.com/' + - 'sec-fetch-mode: navigate' + ... +``` + +## Site-wide content report(#site-wide-content) + +### Customising the report + +In order to customise the columns included in a report you can build a custom extension and apply it to the +SitewideContentReport as necessary. + +The built in `SitewideContentTaxonomy` extension, for instance, adds a custom columns extracted from the `silverstripe/taxonomy` modules, and can be used as a base for developing further extensions: + +For instance, in order to add a new Page field to the report you could add an extension similar to the below: + +```php + use SilverStripe\Core\Extension; + use SilverStripe\Reports\SiteWideContentReport\Reports\SiteWideContentReport; + + class MyReportExtension extends Extension { + protected function updateColumns($itemType, &$columns) { + if($itemType !== 'Pages') { + return; + } + $columns["Price"] = [ + "title" => _t(SitewideContentReport::class . ".Price", "Price"), + "formatting" => function ($value, $item) use ($mainSiteLabel) { + return number_format($value, 2, '.', ','); + }, + ]; + } + } +``` + +The `$columns` array can have any number of items added, where the key of the array represents the +field name to be included. + +Each item can be either a literal string (which will be used as the title), or an array that may contain +the following key => value pairs: + + * `title`: The title to use for the column header + * `format`: A method callback which will take the raw value and original object, and return a formatted + string. + * `datasource`: If the value for this column isn't a direct field on the original object, a custom callback + can be set here. Unlike `format` this callback will only take a single parameter, the original object. + * `printonly`: Set to true if this column is only visible on the print or export-to-csv views. + * `casting`: Specify a field type (e.g. `Text` or `Int`) in order to assist with field casting. This is not + necessary if `formatting` is used. + +### Performance considerations + +#### Large data sets + +If your project has a large number of pages or files, you may experience server timeouts while trying to export +this report to CSV. To avoid this issue, you can either increase your server timeout limit, or you can install +and configure the [silverstripe/gridfieldqueuedexport module](https://github.com/silverstripe/silverstripe-gridfieldqueuedexport) +which allows for CSV generation to offloaded to a queued job in the background. + +An example of configuring this module in your project: + +```php +use SilverStripe\Core\Extension; +use SilverStripe\Forms\GridField\GridFieldComponent; +use SilverStripe\GridfieldQueuedExport\Forms\GridFieldQueuedExportButton; + +class SitewideContentReportQueuedExportExtension extends Extension +{ + protected function updateExportButton(GridFieldComponent &$exportButton) + { + $exportButton = new GridFieldQueuedExportButton('buttons-after-left'); + } +} +``` + +Apply the example Extension above with YAML configuration in your project: + +```yaml +--- +Name: queuedsitewidecontentreport +--- +SilverStripe\Reports\SitewideContentReport\Reports\SitewideContentReport: + extensions: + - SitewideContentReportQueuedExportExtension +``` + diff --git a/tests/php/SecurityReport/MemberReportExtensionTest.php b/tests/php/SecurityReport/Extensions/MemberReportExtensionTest.php similarity index 87% rename from tests/php/SecurityReport/MemberReportExtensionTest.php rename to tests/php/SecurityReport/Extensions/MemberReportExtensionTest.php index 4949c7ab..4b1db777 100644 --- a/tests/php/SecurityReport/MemberReportExtensionTest.php +++ b/tests/php/SecurityReport/Extensions/MemberReportExtensionTest.php @@ -1,11 +1,11 @@