Feature: Add the ability to specify a file path for a comment header

michaeluno · michaeluno · commit 9ce3d1c254d0 · 2022-02-22T20:16:45.000+09:00
New arguments are introduced:

- `comment_header`
 - `text`
 - `path`
 - `class`
 - `type`
diff --git a/README.md b/README.md
@@ -83,7 +83,11 @@ This parameter accepts an array holding options.
     - `exclude_substrings`: (array) sub-strings of paths to exclude from the list. e.g. `[ '.min', '_del', 'temp', 'library', 'vendor' ]`
     - `is_recursive`: (boolean) whether to scan sub-directories.
     - `ignore_note_file_names`: (array) ignore note file names that tell the parser to skip the directory. When one of the files exist in the parsing directory, the directory will be skipped. Default: `[ 'ignore-class-map.txt' ]`,   
-
+ - `comment_header`  : (array, optional)   what header comment to insert at the top of the generated file
+    - `text`  : (string, optional) the header comment to set    
+    - `path`  : (string, optional) the file path to extract the comment from
+    - `class` : (string, optional) the class name to use its doc-block as the header comment
+    - `type`  : (string, optional) indicates what type of data to collect. Accepted values are `DOCBLOCK`, `CONSTANT`. 
 ##### Example
 
 ##### Generating a class map in the script directory.     
diff --git a/changelog.md b/changelog.md
@@ -1,6 +1,7 @@
 # Change Log
 
 ## 1.3.0 - 2022/02/22
+- Added the ability to specify a comment header of a specified file.
 
 ## 1.2.2 - 2022/02/17
 - Fixed a bug that caused an undefined index notice when the `header_class_name` argument was set.
diff --git a/source/Header/HeaderGenerator.php b/source/Header/HeaderGenerator.php
@@ -9,7 +9,18 @@ class HeaderGenerator {
     use traitCodeParser;
 
     public $aItems   = [];
-    public $aOptions = [];
+    public $aOptions = [
+        'text'               => null,   // the direct comment content text
+        'class'              => null,   // the class name tha has the header comment
+        'type'               => null,   // the type of header comment to extract, accepts `DOCBLOCK`, `CONSTANTS`, `COMMENT`
+        'path'               => null,   // the file path where the header comment to extract from
+        'wrap'               => true,   // whether to enclose the comment in the PHP multi-line comment syntax /* */.
+
+        // legacy options
+        'header_class_name'  => null,
+        'header_class_path'  => null,
+        'header_type'        => null,
+    ];
 
     /**
      * HeaderGenerator constructor.
@@ -18,17 +29,42 @@ class HeaderGenerator {
      */
     public function __construct( array $aItems, array $aOptions ) {
         $this->aItems   = $aItems;
-        $this->aOptions = $aOptions;
+        $this->aOptions = $this->___getOptionsFormatted( $aOptions );
     }
+        private function ___getOptionsFormatted( array $aOptions ) {
+            $_aOptions = $aOptions + $this->aOptions;
+            // Backward-compatibility
+            $_aLegacyArgumentsToConvert = [
+                'header_class_path' => 'path',
+                'header_class_name' => 'class',
+                'header_type'       => 'type',
+            ];
+            foreach( $_aLegacyArgumentsToConvert as $_sLegacyKey => $_sCurrentVersionKey ) {
+                if ( ! empty( $_aOptions[ $_sLegacyKey ] ) && empty( $_aOptions[ $_sCurrentVersionKey ] ) ) {
+                    $_aOptions[ $_sCurrentVersionKey ] = $_aOptions[ $_sLegacyKey ];
+                }
+            }
+            return $_aOptions;
+        }
 
     /**
      *
      * @return string
      * @throws \ReflectionException
      */
     public function get() {
-        return $this->___getProjectHeaderComment( $this->aItems, $this->aOptions );
+
+        if ( ! empty( $this->aOptions[ 'text' ] ) ) {
+            return $this->aOptions[ 'wrap' ]
+                ? $this->getMultilineCommentWrapped( $this->aOptions[ 'text' ] )
+                : $this->aOptions[ 'text' ];
+        }
+
+        $_sMultilineComment = $this->___getProjectHeaderComment( $this->aItems, $this->aOptions );
+        return $this->aOptions[ 'wrap' ] ? $_sMultilineComment : $this->getMultiLineCommentUnwrapped( $_sMultilineComment );
+
     }
+
         /**
          * Generates the heading comment from the given path or class name.
          * @param array $aItems
@@ -38,36 +74,42 @@ public function get() {
          */
         private function ___getProjectHeaderComment( array $aItems, array $aOptions )     {
 
-            if ( $aOptions[ 'header_class_path' ] && $aOptions[ 'header_class_name' ] ) {
+            // A pass and a class name is given
+            if ( ! empty( $aOptions[ 'path' ] ) && ! empty( $aOptions[ 'class' ] ) ) {
+                return $this->___getProjectHeaderCommentGenerated($aOptions[ 'path' ], $aOptions[ 'class' ], $aOptions[ 'type' ]);
+            }
+            // A class name is given
+            if ( ! empty( $aOptions[ 'class' ] ) ) {
                 return $this->___getProjectHeaderCommentGenerated(
-                    $aOptions[ 'header_class_path' ],
-                    $aOptions[ 'header_class_name' ],
-                    $aOptions[ 'header_type' ]
+                    isset( $aItems[ $aOptions[ 'class' ] ] )
+                        ? $aItems[ $aOptions[ 'class' ] ][ 'path' ]
+                        : $aOptions[ 'path' ],
+                    $aOptions[ 'class' ],
+                    $aOptions[ 'type' ]
                 );
             }
 
-            if ( $aOptions[ 'header_class_name' ] ) {
-                return $this->___getProjectHeaderCommentGenerated(
-                    isset( $aItems[ $aOptions[ 'header_class_name' ] ] )
-                        ? $aItems[ $aOptions['header_class_name'] ][ 'path' ]
-                        : $aOptions[ 'header_class_path' ],
-                    $aOptions[ 'header_class_name' ],
-                    $aOptions[ 'header_type' ]
-                );
+            if ( empty( $aOptions[ 'path' ] ) ) {
+                return '';
             }
 
-            if ( $aOptions[ 'header_class_path' ] ) {
-                $_aConstructs        = $this->_getDefinedObjectConstructs( '<?php ' . $this->_getPHPCode( $aOptions[ 'header_class_path' ] ) );
-                $_aDefinedClasses    = $_aConstructs[ 'classes' ];
-                $_sHeaderClassName   = isset( $_aDefinedClasses[ 0 ] ) ? $_aDefinedClasses[ 0 ] : '';
-                return $this->___getProjectHeaderCommentGenerated(
-                    $aOptions[ 'header_class_path' ],
-                    $_sHeaderClassName,
-                    $aOptions[ 'header_type' ]
-                );
+            // A pass is given.
+
+            /// Get first found comment block from a file.
+            $_sCommentBlock      = $this->getFirstFoundMultilineComment( file_get_contents( $aOptions[ 'path' ] ) );
+            if ( ! empty( $_sCommentBlock ) ) {
+                return $_sCommentBlock;
             }
 
-            return '';
+            /// Extract a comment block from a fist found class doc-block.
+            $_aConstructs        = $this->_getDefinedObjectConstructs( '<?php ' . $this->_getPHPCode( $aOptions[ 'path' ] ) );
+            $_aDefinedClasses    = $_aConstructs[ 'classes' ];
+            $_sHeaderClassName   = isset( $_aDefinedClasses[ 0 ] ) ? $_aDefinedClasses[ 0 ] : '';
+            return $this->___getProjectHeaderCommentGenerated(
+                $aOptions[ 'path' ],
+                $_sHeaderClassName,
+                $aOptions[ 'type' ]
+            );
 
         }
             /**
@@ -95,7 +137,7 @@ private function ___getProjectHeaderCommentGenerated( $sFilePath, $sClassName, $
                     }
                     return 'DOCBLOCK' === $sHeaderType
                         ? $this->_getClassDocBlock( $_sClassName )
-                        : $this->___generateHeaderComment( $_sClassName );
+                        : $this->getMultilineCommentWrapped( $this->___generateHeaderComment( $_sClassName ) );
                 }
                 return '';
 
@@ -117,16 +159,15 @@ private function ___generateHeaderComment( $sClassName ) {
                     'COPYRIGHT'     => '',  'LICENSE'       => '', 'CONTRIBUTORS'  => '',
                     ];
                 $_aOutputs      = [];
-                $_aOutputs[]    = '/**';
-                $_aOutputs[]    = ( $_aConstants[ 'NAME' ] ? "    " . $_aConstants[ 'NAME' ] . ' ' : '' )
+                $_aOutputs[]    = ( $_aConstants[ 'NAME' ] ? $_aConstants[ 'NAME' ] . ' ' : '' )
                     . ( $_aConstants[ 'VERSION' ]   ? 'v' . $_aConstants[ 'VERSION' ] . ' '  : '' )
                     . ( $_aConstants[ 'AUTHOR' ]    ? 'by ' . $_aConstants[ 'AUTHOR' ] . ' ' : ''  );
-                $_aOutputs[]    = $_aConstants[ 'DESCRIPTION' ]   ? "    ". $_aConstants[ 'DESCRIPTION' ] : '';
-                $_aOutputs[]    = $_aConstants[ 'URI' ]           ? "    ". '<' . $_aConstants[ 'URI' ] . '>' : '';
-                $_aOutputs[]    = ( $_aConstants[ 'COPYRIGHT' ]   ? "    " . $_aConstants[ 'COPYRIGHT' ] : '' )
+                $_aOutputs[]    = $_aConstants[ 'DESCRIPTION' ]   ? $_aConstants[ 'DESCRIPTION' ] : '';
+                $_aOutputs[]    = $_aConstants[ 'URI' ]           ? '<' . $_aConstants[ 'URI' ] . '>' : '';
+                $_aOutputs[]    = ( $_aConstants[ 'COPYRIGHT' ]   ? $_aConstants[ 'COPYRIGHT' ] : '' )
                     . ( $_aConstants[ 'LICENSE' ]    ? '; Licensed under ' . $_aConstants[ 'LICENSE' ] : '' );
-                $_aOutputs[]    = ' */';
-                return implode( PHP_EOL, array_filter( $_aOutputs ) ) . PHP_EOL;
+                return implode( PHP_EOL, array_filter( $_aOutputs ) );
+
             }
 
 }
diff --git a/source/PHPClassMapGenerator.php b/source/PHPClassMapGenerator.php
@@ -1,10 +1,14 @@
 <?php
 /**
- * Helps to generate class maps.
- * 
- * @author       Michael Uno <michael@michaeluno.jp>
- * @copyright    2020- (c) Michael Uno
- * @license      MIT <http://opensource.org/licenses/MIT>
+ * PHP Class Map Generator
+ *
+ * Helps generate class maps of PHP files. The feature includes generating path lists of specified file types.
+ *
+ * @url       https://github.com/michaeluno/php-classmap-generator
+ * @author    Michael Uno <michael@michaeluno.jp>
+ * @copyright 2020- (c) Michael Uno
+ * @license   MIT <http://opensource.org/licenses/MIT>
+ * @version   1.3.0
  */
 
 namespace PHPClassMapGenerator;
@@ -16,8 +20,7 @@
  *
  * This is meant to be used for the callback function for the spl_autoload_register() function.
  *
- * @remark		The parsed class file must have a name of the class defined in the file.
- * @version		1.2.2
+ * @remark The parsed class file must have a name of the class defined in the file.
  */
 class PHPClassMapGenerator implements interfacePHPClassMapGenerator {
 
@@ -126,7 +129,18 @@ public function __construct( $sBaseDirPath, $asScanDirPaths, $sOutputFilePath, a
             'ignore_note_file_names' => ['ignore-class-map.txt'] // 1.1.0 When this option is present and the parsing directory contains a file matching one of the set names, the directory will be skipped.
         ],
 
-    );
+        // Comment header
+        'comment_header'        => [
+            'text'               => '',   // the direct comment content text
+            'class'              => '',   // the class name tha has the header comment
+            'type'               => 'DOCBLOCK',   // the type of header comment to extract, accepts `DOCBLOCK`, `CONSTANT`, `COMMENT`
+            'path'               => '',   // the file path where the header comment to extract from
+        ],
+        // legacy @deprecated 1.3.0
+        'header_class_name'		=> null,
+        'header_class_path'		=> null,
+        'header_type'			=> null,
+    ];
 
     /**
      *
@@ -151,7 +165,7 @@ public function getMap() {
         $_sOpening = $this->aOptions[ 'short_array_syntax' ] ? '[' : 'array(';
         $_sClosing = $this->aOptions[ 'short_array_syntax' ] ? ']' : ')';
         $_aData    = array(
-            mb_convert_encoding( '<?php ' . PHP_EOL . $this->sHeaderComment, 'UTF-8', 'auto' ),
+            mb_convert_encoding( '<?php ' . PHP_EOL . trim( $this->sHeaderComment ) . PHP_EOL, 'UTF-8', 'auto' ),
             'return' === $this->aOptions[ 'output_var_name' ]
                 ? "return {$_sOpening}" . PHP_EOL
                 : $this->aOptions[ 'output_var_name' ] . " = {$_sOpening} " . PHP_EOL,
@@ -250,8 +264,6 @@ private function ___getFileArrayFormatted( array $aFilePaths ) {
 
             }
 
-
-
     /**
      * @param  string       $sBaseDirPath
      * @param  array|string $asScanDirPaths
@@ -274,8 +286,25 @@ protected function _setProperties( $sBaseDirPath, $asScanDirPaths, $sOutputFileP
          * @since  1.1.0
          */
         private function ___getOptionsFormatted( array $aOptions ) {
+
             $aOptions			    = $aOptions + self::$_aStructure_Options;
             $aOptions[ 'search' ]	= $aOptions[ 'search' ] + self::$_aStructure_Options[ 'search' ];
+
+            // Backward compat
+            /// Handle header comment arguments
+            $_aLegacyKeys           = [
+                'header_class_name' => 'class',
+                'header_class_path' => 'path',
+                'header_type'       => 'type',
+            ];
+            foreach( $_aLegacyKeys as $_sLegacyKey => $_sNewKey ) {
+                if ( empty( $aOptions[ $_sLegacyKey ] ) ) {
+                    continue;
+                }
+                $aOptions[ 'comment_header' ][ $_sNewKey ] = $aOptions[ $_sLegacyKey ];
+                unset( $aOptions[ $_sLegacyKey ] );
+            }
+
             return $aOptions;
         }
         /**
@@ -294,7 +323,7 @@ private function ___setItems() {
         }
             private function ___setProjectHeaderComment() {
                 try {
-                    $_oHeaderGenerator    = new HeaderGenerator( $this->aItems, $this->aOptions );
+                    $_oHeaderGenerator    = new HeaderGenerator( $this->aItems, $this->aOptions[ 'comment_header' ] );
                     $this->sHeaderComment = $_oHeaderGenerator->get();
                     if ( ! $this->sHeaderComment ) {
                         throw new \ReflectionException( 'No header comment generated.' );
diff --git a/source/Utility/traitCodeParser.php b/source/Utility/traitCodeParser.php
@@ -6,6 +6,45 @@
 
 trait traitCodeParser {
 
+    /**
+     * @param  $sCode
+     * @return string
+     * @since  1.3.0
+     */
+    static public function getFirstFoundMultilineComment( $sCode ) {
+        preg_match( '/\/\*+?(.*)\*\//Us', $sCode, $_aMatches );
+        return isset( $_aMatches[ 0 ] ) ? ( string ) $_aMatches[ 0 ] : '';
+    }
+
+    /**
+     * @param  string $sMultiLineComment
+     * @return string
+     * @since  1.3.0
+     */
+    static public function getMultiLineCommentUnwrapped( $sMultiLineComment ) {
+        $_sText = '';
+        preg_match( '/\/\*+?(.*)\*\//Us', $sMultiLineComment, $_aMatches );
+        foreach( preg_split("/\r\n|\n|\r/", trim( $_aMatches[ 1 ], '\t\n\r\0\x0B' ) ) as $_i => $_sLine ) {
+            $_sText .= preg_replace( '/^(\s|\/)+\*+(\s|$)/', '', $_sLine ) . PHP_EOL;
+        }
+        return trim( $_sText );
+    }
+
+    /**
+     * @param  string $sMultilineComment
+     * @param  string $sBlockNotation       The first character set to mark the type of block. /** indicates a PHP doc-block. /*! is an important comment not to minify in JavaScript.
+     * @return string
+     * @since  1.3.0
+     */
+    static public function getMultilineCommentWrapped( $sMultilineComment, $sBlockNotation='*' ) {
+        $_sComment = '/*' . $sBlockNotation . PHP_EOL;
+        foreach( preg_split("/\r\n|\n|\r/", $sMultilineComment ) as $_i => $_sLine ) {
+            $_sComment .= ' * ' . $_sLine . PHP_EOL;
+        }
+        $_sComment .= ' */' . PHP_EOL;
+        return $_sComment;
+    }
+
     /**
      * Returns the docblock of the specified class
      * @param   string $sClassName
diff --git a/source/class-map.php b/source/class-map.php
@@ -1,9 +1,13 @@
 <?php 
 /**
-    PHP Class Map Generator v1.1.1 by Michael Uno 
-    Generates PHP class maps for auto-load.
-    <https://en.michaeluno.jp>
-    Michael Uno <2020>; Licensed under MIT
+ * Helps generate class maps of PHP files.
+ *
+ * The feature includes generating path lists of specified file types.
+ * 
+ * @author    Michael Uno <michael@michaeluno.jp>
+ * @copyright 2020- (c) Michael Uno
+ * @license   MIT <http://opensource.org/licenses/MIT>
+ * @version   1.3.0
  */
 return array(
     "PHPClassMapGenerator\\PHPClassMapGenerator" => __DIR__ . "/PHPClassMapGenerator.php", 
diff --git a/test/generate-map-this-project-class.php b/test/generate-map-this-project-class.php
@@ -2,20 +2,19 @@
 
 include( dirname( __DIR__ ) . '/source/autoload.php' );
 
-
 new \PHPClassMapGenerator\PHPClassMapGenerator(
     dirname( __DIR__ ) . '/source', // base dir
     dirname( __DIR__ ) . '/source', // scan dir name
     dirname( __DIR__ ) . '/source/class-map.php',
     [
-
-        'header_class_path'		=> __DIR__ . '/ProjectHeader.php',
-        'header_type'			=> 'CONSTANT', // or 'CONSTANT
         'exclude_classes'       => [ 'ProjectHeader' ],
         'base_dir_var'          => '__DIR__',
         'output_var_name'		=> 'return',
         'search'                => [
             'exclude_dir_names'		=> [ 'test' ],
-        ]
+        ],
+        'comment_header'        => [
+            'path'  => dirname( __DIR__ ) . '/source/PHPClassMapGenerator.php',
+        ],
     ]
 );
