diff --git a/.gitignore b/.gitignore index 5a331df4..46ae02c9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,8 @@ /composer.lock +/var /vendor /vendor-sf3 /vendor-sf4 /vendor-sf5 -.env +/.env +/.phpdoc/cache diff --git a/.phpdoc/template/base.html.twig b/.phpdoc/template/base.html.twig new file mode 100644 index 00000000..1342324c --- /dev/null +++ b/.phpdoc/template/base.html.twig @@ -0,0 +1,8 @@ +{% extends 'layout.html.twig' %} + +{% block javascripts %} + {{ parent() }} + +{% endblock %} diff --git a/.phpdoc/template/components/process_bundle_interfaces.html.twig b/.phpdoc/template/components/process_bundle_interfaces.html.twig new file mode 100644 index 00000000..23343b38 --- /dev/null +++ b/.phpdoc/template/components/process_bundle_interfaces.html.twig @@ -0,0 +1,17 @@ +{% set interfaces_str = include("components/recursive_iterfaces.html.twig", {'class': class}) %} + +{% if "IterableTaskInterface" in interfaces_str %} + iterable +{% endif %} + +{% if "FlushableTaskInterface" in interfaces_str %} + flushable +{% endif %} + +{% if "BlockingTaskInterface" in interfaces_str %} + blocking +{% endif %} + +{% if "TaskInterface" in interfaces_str %} + task +{% endif %} diff --git a/.phpdoc/template/components/recursive_iterfaces.html.twig b/.phpdoc/template/components/recursive_iterfaces.html.twig new file mode 100644 index 00000000..53f6f2e3 --- /dev/null +++ b/.phpdoc/template/components/recursive_iterfaces.html.twig @@ -0,0 +1,22 @@ +{% if class is defined and class %} + {% for interface in class.interfaces %} + {{ interface.name }} + {% if interface.parent|length > 0 %} + {% for parent_interface in interface.parent %} + {% include "components/recursive_iterfaces.html.twig" with {'interface': parent_interface, 'class': false, 'known_interfaces': known_interfaces} %} + {% endfor %} + {% endif %} + {% endfor %} + + {% if class.parent %} + {% include "components/recursive_iterfaces.html.twig" with {'class': class.parent, 'known_interfaces': known_interfaces} %} + {% endif %} +{% endif %} + + +{% if interface is defined %} + {{ interface.name }} + {% for parent_interface in interface.parent %} + {% include "components/recursive_iterfaces.html.twig" with {'interface': parent_interface, 'known_interfaces': known_interfaces} %} + {% endfor %} +{% endif %} diff --git a/.phpdoc/template/components/recursive_namespace_tree.html.twig b/.phpdoc/template/components/recursive_namespace_tree.html.twig new file mode 100644 index 00000000..d7c27d7a --- /dev/null +++ b/.phpdoc/template/components/recursive_namespace_tree.html.twig @@ -0,0 +1,32 @@ +{% if namespace.children|length > 0 or namespace.interfaces|length > 0 or namespace.classes|length > 0 or namespace.traits|length > 0 %} + +{% endif %} diff --git a/.phpdoc/template/components/sidebar.html.twig b/.phpdoc/template/components/sidebar.html.twig new file mode 100644 index 00000000..31433bb0 --- /dev/null +++ b/.phpdoc/template/components/sidebar.html.twig @@ -0,0 +1,68 @@ + + + diff --git a/.phpdoc/template/components/table-of-contents.html.twig b/.phpdoc/template/components/table-of-contents.html.twig new file mode 100644 index 00000000..a47dc2ee --- /dev/null +++ b/.phpdoc/template/components/table-of-contents.html.twig @@ -0,0 +1,81 @@ +{% if packages|default([]) is not empty %} +

+ Packages + +

+ +
+ {% for package in packages %} +
{{ package|route('class:short') }}
+ {% endfor %} +
+{% endif %} + +{% if namespaces|default([]) is not empty %} +

+ Namespaces + +

+ +
+ {% for namespace in namespaces %} +
{{ namespace|route('class:short') }}
+ {% endfor %} +
+{% endif %} + +{% if node.interfaces is not empty or node.classes is not empty or node.traits is not empty %} +

+ Interfaces, Classes and Traits + +

+ +
+ {% for interface in node.interfaces %} +
{{ interface|route('class:short') }}
+
{{ interface.summary }}
+ {% endfor %} + + {% for class in node.classes %} +
+ {{ class|route('class:short') }} + {% set task_interfaces_str = include("components/process_bundle_interfaces.html.twig", {'class': class})|spaceless|capitalize %} + {% if task_interfaces_str|length > 0 %} + ({{ task_interfaces_str }}) + {% endif %} +
+
{{ class.summary }}
+ {% endfor %} + + {% for trait in node.traits %} +
{{ trait|route('class:short') }}
+
{{ trait.summary }}
+ {% endfor %} +
+{% endif %} + +{% set constants = constants(node) %} +{% set properties = properties(node) %} +{% set methods = methods(node) %} + +{% if constants is not empty or node.functions is not empty or methods is not empty or properties is not empty %} +

+ Table of Contents + +

+ +
+ {% for constant in constants(node)|sortByVisibility %} + {{ include('components/table-of-contents-entry.html.twig', {'type': 'constant', 'node': constant}) }} + {% endfor %} + {% for property in properties(node)|sortByVisibility %} + {{ include('components/table-of-contents-entry.html.twig', {'type': 'property', 'node': property}) }} + {% endfor %} + {% for method in methods(node)|sortByVisibility %} + {{ include('components/table-of-contents-entry.html.twig', {'type': 'method', 'node': method}) }} + {% endfor %} + {% for function in node.functions|default([]) %} + {{ include('components/table-of-contents-entry.html.twig', {'type': 'function', 'node': function}) }} + {% endfor %} +
+{% endif %} diff --git a/.phpdoc/template/components/tags.html.twig b/.phpdoc/template/components/tags.html.twig new file mode 100644 index 00000000..8d00ce00 --- /dev/null +++ b/.phpdoc/template/components/tags.html.twig @@ -0,0 +1,60 @@ +{# + # Override to add @example features + # @see https://github.com/phpDocumentor/phpDocumentor/blob/master/data/templates/default/components/tags.html.twig + #} +{% set tags = node.tags|filter((v,k) => k not in ['var', 'param', 'property', 'property-read', 'property-write', 'method', 'return', 'package', 'api', 'example']) %} + +{% for tagName,tags in node.tags if tagName in ['example'] %} + {% if loop.first %} +
+ Examples + +
+ {% endif %} +
+ {% for tag in tags %} +
+ {{ tag.description | description | markdown }} +
+
+ {% if tag.example %} + 
{{ tag.example|escape }}
+ {% endif %} +
+ {% endfor %} +
+{% endfor %} + +{% if tags|length > 0 %} +
+ Tags + +
+
+ {% for name,seriesOfTag in tags %} + {% for tag in seriesOfTag %} +
+ {{ name }} +
+
+ {% if tag.version %} + {{ tag.version }} + {% endif %} + {% if tag.type %} + {{ tag.type|route('class:short')|join('|')|raw }} + {% endif %} + {% if tag.reference %} + {{ tag.reference|route('class:short')|join('|')|raw }} + {% endif %} + {% if tag.link %} + {% if tag.description is not empty %} {{ tag.description | description | markdown }} {% else %} {{ tag.link }} {% endif %} + {% endif %} + + {% if not tag.link %} + {{ include('components/description.html.twig', {'node': tag}) }} + {% endif %} +
+ {% endfor %} + {% endfor %} +
+{% endif %} diff --git a/.phpdoc/template/css/custom.css.twig b/.phpdoc/template/css/custom.css.twig new file mode 100644 index 00000000..f30167a2 --- /dev/null +++ b/.phpdoc/template/css/custom.css.twig @@ -0,0 +1,66 @@ +{% include 'css/prism.css' %} + +/* Sidebar improvements */ +.sidebar-item:before { + content: ''; + background: transparent url('data:image/svg+xml;utf8,{{ include('icons/method.svg.twig')|trim|raw }}') no-repeat center center; + width: 1.25rem; + height: 1.25rem; + line-height: 1.25rem; + border-radius: 50%; + font-weight: 600; + color: white; + text-align: center; + font-size: .75rem; + margin-top: .2rem; + margin-right: .3rem; + display: inline-block; +} + +.sidebar-item.-interface:before { + content: 'I'; + background: transparent url('data:image/svg+xml;utf8,{{ include('icons/interface.svg.twig')|trim|raw }}') no-repeat center center; +} + +.sidebar-item.-class:before { + content: 'C'; + background: transparent url('data:image/svg+xml;utf8,{{ include('icons/class.svg.twig')|trim|raw }}') no-repeat center center; +} + +.sidebar-item.-class.-abstract:before { + content: 'A'; + background: transparent url('data:image/svg+xml;utf8,{{ include('icons/abstract.svg.twig')|trim|raw }}') no-repeat center center; +} + +.sidebar-item.-trait:before { + content: 'T'; + background: transparent url('data:image/svg+xml;utf8,{{ include('icons/trait.svg.twig')|trim|raw }}') no-repeat center center; +} + +.phpdocumentor .phpdocumentor-sidebar .phpdocumentor-list .phpdocumentor-list { + padding-top: 0; + padding-left: 0; +} + +.processbundle-task-interfaces { + padding-left: 1rem; + color: #aaaaaa; +} + +/* Overrides */ +.phpdocumentor-table-of-contents .phpdocumentor-table-of-contents__entry.-interface:before { + background: transparent url('data:image/svg+xml;utf8,{{ include('icons/interface.svg.twig')|trim|raw }}') no-repeat center center; +} + +.phpdocumentor-table-of-contents .phpdocumentor-table-of-contents__entry.-class:before { + background: transparent url('data:image/svg+xml;utf8,{{ include('icons/class.svg.twig')|trim|raw }}') no-repeat center center; +} + +.phpdocumentor-table-of-contents .phpdocumentor-table-of-contents__entry.-class.-abstract:before { + content: 'A'; + background: transparent url('data:image/svg+xml;utf8,{{ include('icons/abstract.svg.twig')|trim|raw }}') no-repeat center center; +} + +.phpdocumentor-table-of-contents .phpdocumentor-table-of-contents__entry.-trait:before { + background: transparent url('data:image/svg+xml;utf8,{{ include('icons/trait.svg.twig')|trim|raw }}') no-repeat center center; +} diff --git a/.phpdoc/template/css/prism.css b/.phpdoc/template/css/prism.css new file mode 100644 index 00000000..70ecdc6c --- /dev/null +++ b/.phpdoc/template/css/prism.css @@ -0,0 +1,143 @@ +/* PrismJS 1.23.0 +https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript+javadoclike+markup-templating+php+phpdoc+php-extras+yaml */ +/** + * prism.js default theme for JavaScript, CSS and HTML + * Based on dabblet (http://dabblet.com) + * @author Lea Verou + */ + +code[class*="language-"], +pre[class*="language-"] { + color: black; + background: none; + text-shadow: 0 1px white; + font-family: Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace; + font-size: 1em; + text-align: left; + white-space: pre; + word-spacing: normal; + word-break: normal; + word-wrap: normal; + line-height: 1.5; + + -moz-tab-size: 4; + -o-tab-size: 4; + tab-size: 4; + + -webkit-hyphens: none; + -moz-hyphens: none; + -ms-hyphens: none; + hyphens: none; +} + +pre[class*="language-"]::-moz-selection, pre[class*="language-"] ::-moz-selection, +code[class*="language-"]::-moz-selection, code[class*="language-"] ::-moz-selection { + text-shadow: none; + background: #b3d4fc; +} + +pre[class*="language-"]::selection, pre[class*="language-"] ::selection, +code[class*="language-"]::selection, code[class*="language-"] ::selection { + text-shadow: none; + background: #b3d4fc; +} + +@media print { + code[class*="language-"], + pre[class*="language-"] { + text-shadow: none; + } +} + +/* Code blocks */ +pre[class*="language-"] { + padding: 1em; + margin: .5em 0; + overflow: auto; +} + +:not(pre) > code[class*="language-"], +pre[class*="language-"] { + background: #f5f2f0; +} + +/* Inline code */ +:not(pre) > code[class*="language-"] { + padding: .1em; + border-radius: .3em; + white-space: normal; +} + +.token.comment, +.token.prolog, +.token.doctype, +.token.cdata { + color: slategray; +} + +.token.punctuation { + color: #999; +} + +.token.namespace { + opacity: .7; +} + +.token.property, +.token.tag, +.token.boolean, +.token.number, +.token.constant, +.token.symbol, +.token.deleted { + color: #905; +} + +.token.selector, +.token.attr-name, +.token.string, +.token.char, +.token.builtin, +.token.inserted { + color: #690; +} + +.token.operator, +.token.entity, +.token.url, +.language-css .token.string, +.style .token.string { + color: #9a6e3a; + /* This background color was intended by the author of this theme. */ + background: hsla(0, 0%, 100%, .5); +} + +.token.atrule, +.token.attr-value, +.token.keyword { + color: #07a; +} + +.token.function, +.token.class-name { + color: #DD4A68; +} + +.token.regex, +.token.important, +.token.variable { + color: #e90; +} + +.token.important, +.token.bold { + font-weight: bold; +} +.token.italic { + font-style: italic; +} + +.token.entity { + cursor: help; +} + diff --git a/.phpdoc/template/icons/abstract.svg.twig b/.phpdoc/template/icons/abstract.svg.twig new file mode 100644 index 00000000..0eb51f91 --- /dev/null +++ b/.phpdoc/template/icons/abstract.svg.twig @@ -0,0 +1 @@ + diff --git a/.phpdoc/template/icons/class.svg.twig b/.phpdoc/template/icons/class.svg.twig new file mode 100644 index 00000000..65d42b01 --- /dev/null +++ b/.phpdoc/template/icons/class.svg.twig @@ -0,0 +1 @@ + diff --git a/.phpdoc/template/icons/interface.svg.twig b/.phpdoc/template/icons/interface.svg.twig new file mode 100644 index 00000000..e1648735 --- /dev/null +++ b/.phpdoc/template/icons/interface.svg.twig @@ -0,0 +1 @@ + diff --git a/.phpdoc/template/icons/trait.svg.twig b/.phpdoc/template/icons/trait.svg.twig new file mode 100644 index 00000000..2b2dad83 --- /dev/null +++ b/.phpdoc/template/icons/trait.svg.twig @@ -0,0 +1 @@ + diff --git a/.phpdoc/template/js/prism.js b/.phpdoc/template/js/prism.js new file mode 100644 index 00000000..f5e64e8b --- /dev/null +++ b/.phpdoc/template/js/prism.js @@ -0,0 +1,13 @@ +/* PrismJS 1.23.0 +https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript+javadoclike+markup-templating+php+phpdoc+php-extras+yaml */ +var _self="undefined"!=typeof window?window:"undefined"!=typeof WorkerGlobalScope&&self instanceof WorkerGlobalScope?self:{},Prism=function(u){var c=/\blang(?:uage)?-([\w-]+)\b/i,n=0,M={manual:u.Prism&&u.Prism.manual,disableWorkerMessageHandler:u.Prism&&u.Prism.disableWorkerMessageHandler,util:{encode:function e(n){return n instanceof W?new W(n.type,e(n.content),n.alias):Array.isArray(n)?n.map(e):n.replace(/&/g,"&").replace(/=l.reach);y+=m.value.length,m=m.next){var k=m.value;if(r.length>n.length)return;if(!(k instanceof W)){var b,x=1;if(h){if(!(b=z(p,y,n,f)))break;var w=b.index,A=b.index+b[0].length,P=y;for(P+=m.value.length;P<=w;)m=m.next,P+=m.value.length;if(P-=m.value.length,y=P,m.value instanceof W)continue;for(var S=m;S!==r.tail&&(Pl.reach&&(l.reach=N);var j=m.prev;O&&(j=I(r,j,O),y+=O.length),q(r,j,x);var C=new W(o,g?M.tokenize(E,g):E,d,E);if(m=I(r,j,C),L&&I(r,m,L),1l.reach&&(l.reach=_.reach)}}}}}}(e,a,n,a.head,0),function(e){var n=[],r=e.head.next;for(;r!==e.tail;)n.push(r.value),r=r.next;return n}(a)},hooks:{all:{},add:function(e,n){var r=M.hooks.all;r[e]=r[e]||[],r[e].push(n)},run:function(e,n){var r=M.hooks.all[e];if(r&&r.length)for(var t,a=0;t=r[a++];)t(n)}},Token:W};function W(e,n,r,t){this.type=e,this.content=n,this.alias=r,this.length=0|(t||"").length}function z(e,n,r,t){e.lastIndex=n;var a=e.exec(r);if(a&&t&&a[1]){var i=a[1].length;a.index+=i,a[0]=a[0].slice(i)}return a}function i(){var e={value:null,prev:null,next:null},n={value:null,prev:e,next:null};e.next=n,this.head=e,this.tail=n,this.length=0}function I(e,n,r){var t=n.next,a={value:r,prev:n,next:t};return n.next=a,t.prev=a,e.length++,a}function q(e,n,r){for(var t=n.next,a=0;a"+a.content+""},!u.document)return u.addEventListener&&(M.disableWorkerMessageHandler||u.addEventListener("message",function(e){var n=JSON.parse(e.data),r=n.language,t=n.code,a=n.immediateClose;u.postMessage(M.highlight(t,M.languages[r],r)),a&&u.close()},!1)),M;var e=M.util.currentScript();function r(){M.manual||M.highlightAll()}if(e&&(M.filename=e.src,e.hasAttribute("data-manual")&&(M.manual=!0)),!M.manual){var t=document.readyState;"loading"===t||"interactive"===t&&e&&e.defer?document.addEventListener("DOMContentLoaded",r):window.requestAnimationFrame?window.requestAnimationFrame(r):window.setTimeout(r,16)}return M}(_self);"undefined"!=typeof module&&module.exports&&(module.exports=Prism),"undefined"!=typeof global&&(global.Prism=Prism); +Prism.languages.markup={comment://,prolog:/<\?[\s\S]+?\?>/,doctype:{pattern:/"'[\]]|"[^"]*"|'[^']*')+(?:\[(?:[^<"'\]]|"[^"]*"|'[^']*'|<(?!!--)|)*\]\s*)?>/i,greedy:!0,inside:{"internal-subset":{pattern:/(\[)[\s\S]+(?=\]>$)/,lookbehind:!0,greedy:!0,inside:null},string:{pattern:/"[^"]*"|'[^']*'/,greedy:!0},punctuation:/^$|[[\]]/,"doctype-tag":/^DOCTYPE/,name:/[^\s<>'"]+/}},cdata://i,tag:{pattern:/<\/?(?!\d)[^\s>\/=$<%]+(?:\s(?:\s*[^\s>\/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s'">=]+(?=[\s>]))|(?=[\s/>])))+)?\s*\/?>/,greedy:!0,inside:{tag:{pattern:/^<\/?[^\s>\/]+/,inside:{punctuation:/^<\/?/,namespace:/^[^\s>\/:]+:/}},"attr-value":{pattern:/=\s*(?:"[^"]*"|'[^']*'|[^\s'">=]+)/,inside:{punctuation:[{pattern:/^=/,alias:"attr-equals"},/"|'/]}},punctuation:/\/?>/,"attr-name":{pattern:/[^\s>\/]+/,inside:{namespace:/^[^\s>\/:]+:/}}}},entity:[{pattern:/&[\da-z]{1,8};/i,alias:"named-entity"},/&#x?[\da-f]{1,8};/i]},Prism.languages.markup.tag.inside["attr-value"].inside.entity=Prism.languages.markup.entity,Prism.languages.markup.doctype.inside["internal-subset"].inside=Prism.languages.markup,Prism.hooks.add("wrap",function(a){"entity"===a.type&&(a.attributes.title=a.content.replace(/&/,"&"))}),Object.defineProperty(Prism.languages.markup.tag,"addInlined",{value:function(a,e){var s={};s["language-"+e]={pattern:/(^$)/i,lookbehind:!0,inside:Prism.languages[e]},s.cdata=/^$/i;var n={"included-cdata":{pattern://i,inside:s}};n["language-"+e]={pattern:/[\s\S]+/,inside:Prism.languages[e]};var t={};t[a]={pattern:RegExp("(<__[^>]*>)(?:))*\\]\\]>|(?!)".replace(/__/g,function(){return a}),"i"),lookbehind:!0,greedy:!0,inside:n},Prism.languages.insertBefore("markup","cdata",t)}}),Prism.languages.html=Prism.languages.markup,Prism.languages.mathml=Prism.languages.markup,Prism.languages.svg=Prism.languages.markup,Prism.languages.xml=Prism.languages.extend("markup",{}),Prism.languages.ssml=Prism.languages.xml,Prism.languages.atom=Prism.languages.xml,Prism.languages.rss=Prism.languages.xml; +!function(s){var e=/("|')(?:\\(?:\r\n|[\s\S])|(?!\1)[^\\\r\n])*\1/;s.languages.css={comment:/\/\*[\s\S]*?\*\//,atrule:{pattern:/@[\w-](?:[^;{\s]|\s+(?![\s{]))*(?:;|(?=\s*\{))/,inside:{rule:/^@[\w-]+/,"selector-function-argument":{pattern:/(\bselector\s*\(\s*(?![\s)]))(?:[^()\s]|\s+(?![\s)])|\((?:[^()]|\([^()]*\))*\))+(?=\s*\))/,lookbehind:!0,alias:"selector"},keyword:{pattern:/(^|[^\w-])(?:and|not|only|or)(?![\w-])/,lookbehind:!0}}},url:{pattern:RegExp("\\burl\\((?:"+e.source+"|(?:[^\\\\\r\n()\"']|\\\\[^])*)\\)","i"),greedy:!0,inside:{function:/^url/i,punctuation:/^\(|\)$/,string:{pattern:RegExp("^"+e.source+"$"),alias:"url"}}},selector:RegExp("[^{}\\s](?:[^{};\"'\\s]|\\s+(?![\\s{])|"+e.source+")*(?=\\s*\\{)"),string:{pattern:e,greedy:!0},property:/(?!\s)[-_a-z\xA0-\uFFFF](?:(?!\s)[-\w\xA0-\uFFFF])*(?=\s*:)/i,important:/!important\b/i,function:/[-a-z0-9]+(?=\()/i,punctuation:/[(){};:,]/},s.languages.css.atrule.inside.rest=s.languages.css;var t=s.languages.markup;t&&(t.tag.addInlined("style","css"),s.languages.insertBefore("inside","attr-value",{"style-attr":{pattern:/(^|["'\s])style\s*=\s*(?:"[^"]*"|'[^']*')/i,lookbehind:!0,inside:{"attr-value":{pattern:/=\s*(?:"[^"]*"|'[^']*'|[^\s'">=]+)/,inside:{style:{pattern:/(["'])[\s\S]+(?=["']$)/,lookbehind:!0,alias:"language-css",inside:s.languages.css},punctuation:[{pattern:/^=/,alias:"attr-equals"},/"|'/]}},"attr-name":/^style/i}}},t.tag))}(Prism); +Prism.languages.clike={comment:[{pattern:/(^|[^\\])\/\*[\s\S]*?(?:\*\/|$)/,lookbehind:!0,greedy:!0},{pattern:/(^|[^\\:])\/\/.*/,lookbehind:!0,greedy:!0}],string:{pattern:/(["'])(?:\\(?:\r\n|[\s\S])|(?!\1)[^\\\r\n])*\1/,greedy:!0},"class-name":{pattern:/(\b(?:class|interface|extends|implements|trait|instanceof|new)\s+|\bcatch\s+\()[\w.\\]+/i,lookbehind:!0,inside:{punctuation:/[.\\]/}},keyword:/\b(?:if|else|while|do|for|return|in|instanceof|function|new|try|throw|catch|finally|null|break|continue)\b/,boolean:/\b(?:true|false)\b/,function:/\w+(?=\()/,number:/\b0x[\da-f]+\b|(?:\b\d+(?:\.\d*)?|\B\.\d+)(?:e[+-]?\d+)?/i,operator:/[<>]=?|[!=]=?=?|--?|\+\+?|&&?|\|\|?|[?*/~^%]/,punctuation:/[{}[\];(),.:]/}; +Prism.languages.javascript=Prism.languages.extend("clike",{"class-name":[Prism.languages.clike["class-name"],{pattern:/(^|[^$\w\xA0-\uFFFF])(?!\s)[_$A-Z\xA0-\uFFFF](?:(?!\s)[$\w\xA0-\uFFFF])*(?=\.(?:prototype|constructor))/,lookbehind:!0}],keyword:[{pattern:/((?:^|})\s*)catch\b/,lookbehind:!0},{pattern:/(^|[^.]|\.\.\.\s*)\b(?:as|async(?=\s*(?:function\b|\(|[$\w\xA0-\uFFFF]|$))|await|break|case|class|const|continue|debugger|default|delete|do|else|enum|export|extends|finally(?=\s*(?:\{|$))|for|from(?=\s*(?:['"]|$))|function|(?:get|set)(?=\s*(?:[\[$\w\xA0-\uFFFF]|$))|if|implements|import|in|instanceof|interface|let|new|null|of|package|private|protected|public|return|static|super|switch|this|throw|try|typeof|undefined|var|void|while|with|yield)\b/,lookbehind:!0}],function:/#?(?!\s)[_$a-zA-Z\xA0-\uFFFF](?:(?!\s)[$\w\xA0-\uFFFF])*(?=\s*(?:\.\s*(?:apply|bind|call)\s*)?\()/,number:/\b(?:(?:0[xX](?:[\dA-Fa-f](?:_[\dA-Fa-f])?)+|0[bB](?:[01](?:_[01])?)+|0[oO](?:[0-7](?:_[0-7])?)+)n?|(?:\d(?:_\d)?)+n|NaN|Infinity)\b|(?:\b(?:\d(?:_\d)?)+\.?(?:\d(?:_\d)?)*|\B\.(?:\d(?:_\d)?)+)(?:[Ee][+-]?(?:\d(?:_\d)?)+)?/,operator:/--|\+\+|\*\*=?|=>|&&=?|\|\|=?|[!=]==|<<=?|>>>?=?|[-+*/%&|^!=<>]=?|\.{3}|\?\?=?|\?\.?|[~:]/}),Prism.languages.javascript["class-name"][0].pattern=/(\b(?:class|interface|extends|implements|instanceof|new)\s+)[\w.\\]+/,Prism.languages.insertBefore("javascript","keyword",{regex:{pattern:/((?:^|[^$\w\xA0-\uFFFF."'\])\s]|\b(?:return|yield))\s*)\/(?:\[(?:[^\]\\\r\n]|\\.)*]|\\.|[^/\\\[\r\n])+\/[gimyus]{0,6}(?=(?:\s|\/\*(?:[^*]|\*(?!\/))*\*\/)*(?:$|[\r\n,.;:})\]]|\/\/))/,lookbehind:!0,greedy:!0,inside:{"regex-source":{pattern:/^(\/)[\s\S]+(?=\/[a-z]*$)/,lookbehind:!0,alias:"language-regex",inside:Prism.languages.regex},"regex-flags":/[a-z]+$/,"regex-delimiter":/^\/|\/$/}},"function-variable":{pattern:/#?(?!\s)[_$a-zA-Z\xA0-\uFFFF](?:(?!\s)[$\w\xA0-\uFFFF])*(?=\s*[=:]\s*(?:async\s*)?(?:\bfunction\b|(?:\((?:[^()]|\([^()]*\))*\)|(?!\s)[_$a-zA-Z\xA0-\uFFFF](?:(?!\s)[$\w\xA0-\uFFFF])*)\s*=>))/,alias:"function"},parameter:[{pattern:/(function(?:\s+(?!\s)[_$a-zA-Z\xA0-\uFFFF](?:(?!\s)[$\w\xA0-\uFFFF])*)?\s*\(\s*)(?!\s)(?:[^()\s]|\s+(?![\s)])|\([^()]*\))+(?=\s*\))/,lookbehind:!0,inside:Prism.languages.javascript},{pattern:/(?!\s)[_$a-zA-Z\xA0-\uFFFF](?:(?!\s)[$\w\xA0-\uFFFF])*(?=\s*=>)/i,inside:Prism.languages.javascript},{pattern:/(\(\s*)(?!\s)(?:[^()\s]|\s+(?![\s)])|\([^()]*\))+(?=\s*\)\s*=>)/,lookbehind:!0,inside:Prism.languages.javascript},{pattern:/((?:\b|\s|^)(?!(?:as|async|await|break|case|catch|class|const|continue|debugger|default|delete|do|else|enum|export|extends|finally|for|from|function|get|if|implements|import|in|instanceof|interface|let|new|null|of|package|private|protected|public|return|set|static|super|switch|this|throw|try|typeof|undefined|var|void|while|with|yield)(?![$\w\xA0-\uFFFF]))(?:(?!\s)[_$a-zA-Z\xA0-\uFFFF](?:(?!\s)[$\w\xA0-\uFFFF])*\s*)\(\s*|\]\s*\(\s*)(?!\s)(?:[^()\s]|\s+(?![\s)])|\([^()]*\))+(?=\s*\)\s*\{)/,lookbehind:!0,inside:Prism.languages.javascript}],constant:/\b[A-Z](?:[A-Z_]|\dx?)*\b/}),Prism.languages.insertBefore("javascript","string",{"template-string":{pattern:/`(?:\\[\s\S]|\${(?:[^{}]|{(?:[^{}]|{[^}]*})*})+}|(?!\${)[^\\`])*`/,greedy:!0,inside:{"template-punctuation":{pattern:/^`|`$/,alias:"string"},interpolation:{pattern:/((?:^|[^\\])(?:\\{2})*)\${(?:[^{}]|{(?:[^{}]|{[^}]*})*})+}/,lookbehind:!0,inside:{"interpolation-punctuation":{pattern:/^\${|}$/,alias:"punctuation"},rest:Prism.languages.javascript}},string:/[\s\S]+/}}}),Prism.languages.markup&&Prism.languages.markup.tag.addInlined("script","javascript"),Prism.languages.js=Prism.languages.javascript; +!function(h){function v(e,n){return"___"+e.toUpperCase()+n+"___"}Object.defineProperties(h.languages["markup-templating"]={},{buildPlaceholders:{value:function(a,r,e,o){if(a.language===r){var c=a.tokenStack=[];a.code=a.code.replace(e,function(e){if("function"==typeof o&&!o(e))return e;for(var n,t=c.length;-1!==a.code.indexOf(n=v(r,t));)++t;return c[t]=e,n}),a.grammar=h.languages.markup}}},tokenizePlaceholders:{value:function(p,k){if(p.language===k&&p.tokenStack){p.grammar=h.languages[k];var m=0,d=Object.keys(p.tokenStack);!function e(n){for(var t=0;t=d.length);t++){var a=n[t];if("string"==typeof a||a.content&&"string"==typeof a.content){var r=d[m],o=p.tokenStack[r],c="string"==typeof a?a:a.content,i=v(k,r),u=c.indexOf(i);if(-1|\?\?=?|\.{3}|\??->|[!=]=?=?|::|\*\*=?|--|\+\+|&&|\|\||<<|>>|[?~]|[/^|%*&<>.+-]=?/,s=/[{}\[\](),:;]/;a.languages.php={delimiter:{pattern:/\?>$|^<\?(?:php(?=\s)|=)?/i,alias:"important"},comment:e,variable:/\$+(?:\w+\b|(?={))/i,package:{pattern:/(namespace\s+|use\s+(?:function\s+)?)(?:\\?\b[a-z_]\w*)+\b(?!\\)/i,lookbehind:!0,inside:{punctuation:/\\/}},"class-name-definition":{pattern:/(\b(?:class|enum|interface|trait)\s+)\b[a-z_]\w*(?!\\)\b/i,lookbehind:!0,alias:"class-name"},keyword:[{pattern:/(\(\s*)\b(?:bool|boolean|int|integer|float|string|object|array)\b(?=\s*\))/i,alias:"type-casting",greedy:!0,lookbehind:!0},{pattern:/([(,?]\s*)\b(?:bool|int|float|string|object|array(?!\s*\()|mixed|self|static|callable|iterable|(?:null|false)(?=\s*\|))\b(?=\s*\$)/i,alias:"type-hint",greedy:!0,lookbehind:!0},{pattern:/([(,?]\s*[a-z0-9_|]\|\s*)(?:null|false)\b(?=\s*\$)/i,alias:"type-hint",greedy:!0,lookbehind:!0},{pattern:/(\)\s*:\s*(?:\?\s*)?)\b(?:bool|int|float|string|object|void|array(?!\s*\()|mixed|self|static|callable|iterable|(?:null|false)(?=\s*\|))\b/i,alias:"return-type",greedy:!0,lookbehind:!0},{pattern:/(\)\s*:\s*(?:\?\s*)?[a-z0-9_|]\|\s*)(?:null|false)\b/i,alias:"return-type",greedy:!0,lookbehind:!0},{pattern:/\b(?:bool|int|float|string|object|void|array(?!\s*\()|mixed|iterable|(?:null|false)(?=\s*\|))\b/i,alias:"type-declaration",greedy:!0},{pattern:/(\|\s*)(?:null|false)\b/i,alias:"type-declaration",greedy:!0,lookbehind:!0},{pattern:/\b(?:parent|self|static)(?=\s*::)/i,alias:"static-context",greedy:!0},/\b(?:__halt_compiler|abstract|and|array|as|break|callable|case|catch|class|clone|const|continue|declare|default|die|do|echo|else|elseif|empty|enddeclare|endfor|endforeach|endif|endswitch|endwhile|enum|eval|exit|extends|final|finally|for|foreach|function|global|goto|if|implements|include|include_once|instanceof|insteadof|interface|isset|list|namespace|match|new|or|parent|print|private|protected|public|require|require_once|return|self|static|switch|throw|trait|try|unset|use|var|while|xor|yield)\b/i],"argument-name":{pattern:/([(,]\s+)\b[a-z_]\w*(?=\s*:(?!:))/i,lookbehind:!0},"class-name":[{pattern:/(\b(?:extends|implements|instanceof|new(?!\s+self|\s+static))\s+|\bcatch\s*\()\b[a-z_]\w*(?!\\)\b/i,greedy:!0,lookbehind:!0},{pattern:/(\|\s*)\b[a-z_]\w*(?!\\)\b/i,greedy:!0,lookbehind:!0},{pattern:/\b[a-z_]\w*(?!\\)\b(?=\s*\|)/i,greedy:!0},{pattern:/(\|\s*)(?:\\?\b[a-z_]\w*)+\b/i,alias:"class-name-fully-qualified",greedy:!0,lookbehind:!0,inside:{punctuation:/\\/}},{pattern:/(?:\\?\b[a-z_]\w*)+\b(?=\s*\|)/i,alias:"class-name-fully-qualified",greedy:!0,inside:{punctuation:/\\/}},{pattern:/(\b(?:extends|implements|instanceof|new(?!\s+self\b|\s+static\b))\s+|\bcatch\s*\()(?:\\?\b[a-z_]\w*)+\b(?!\\)/i,alias:"class-name-fully-qualified",greedy:!0,lookbehind:!0,inside:{punctuation:/\\/}},{pattern:/\b[a-z_]\w*(?=\s*\$)/i,alias:"type-declaration",greedy:!0},{pattern:/(?:\\?\b[a-z_]\w*)+(?=\s*\$)/i,alias:["class-name-fully-qualified","type-declaration"],greedy:!0,inside:{punctuation:/\\/}},{pattern:/\b[a-z_]\w*(?=\s*::)/i,alias:"static-context",greedy:!0},{pattern:/(?:\\?\b[a-z_]\w*)+(?=\s*::)/i,alias:["class-name-fully-qualified","static-context"],greedy:!0,inside:{punctuation:/\\/}},{pattern:/([(,?]\s*)[a-z_]\w*(?=\s*\$)/i,alias:"type-hint",greedy:!0,lookbehind:!0},{pattern:/([(,?]\s*)(?:\\?\b[a-z_]\w*)+(?=\s*\$)/i,alias:["class-name-fully-qualified","type-hint"],greedy:!0,lookbehind:!0,inside:{punctuation:/\\/}},{pattern:/(\)\s*:\s*(?:\?\s*)?)\b[a-z_]\w*(?!\\)\b/i,alias:"return-type",greedy:!0,lookbehind:!0},{pattern:/(\)\s*:\s*(?:\?\s*)?)(?:\\?\b[a-z_]\w*)+\b(?!\\)/i,alias:["class-name-fully-qualified","return-type"],greedy:!0,lookbehind:!0,inside:{punctuation:/\\/}}],constant:t,function:/\w+\s*(?=\()/,property:{pattern:/(->)[\w]+/,lookbehind:!0},number:i,operator:n,punctuation:s};var l={pattern:/{\$(?:{(?:{[^{}]+}|[^{}]+)}|[^{}])+}|(^|[^\\{])\$+(?:\w+(?:\[[^\r\n\[\]]+\]|->\w+)*)/,lookbehind:!0,inside:a.languages.php},r=[{pattern:/<<<'([^']+)'[\r\n](?:.*[\r\n])*?\1;/,alias:"nowdoc-string",greedy:!0,inside:{delimiter:{pattern:/^<<<'[^']+'|[a-z_]\w*;$/i,alias:"symbol",inside:{punctuation:/^<<<'?|[';]$/}}}},{pattern:/<<<(?:"([^"]+)"[\r\n](?:.*[\r\n])*?\1;|([a-z_]\w*)[\r\n](?:.*[\r\n])*?\2;)/i,alias:"heredoc-string",greedy:!0,inside:{delimiter:{pattern:/^<<<(?:"[^"]+"|[a-z_]\w*)|[a-z_]\w*;$/i,alias:"symbol",inside:{punctuation:/^<<<"?|[";]$/}},interpolation:l}},{pattern:/`(?:\\[\s\S]|[^\\`])*`/,alias:"backtick-quoted-string",greedy:!0},{pattern:/'(?:\\[\s\S]|[^\\'])*'/,alias:"single-quoted-string",greedy:!0},{pattern:/"(?:\\[\s\S]|[^\\"])*"/,alias:"double-quoted-string",greedy:!0,inside:{interpolation:l}}];a.languages.insertBefore("php","variable",{string:r}),a.languages.insertBefore("php","variable",{attribute:{pattern:/#\[(?:[^"'\/#]|\/(?![*/])|\/\/.*$|#(?!\[).*$|\/\*(?:[^*]|\*(?!\/))*\*\/|"(?:\\[\s\S]|[^\\"])*"|'(?:\\[\s\S]|[^\\'])*')+\](?=\s*[a-z$#])/im,greedy:!0,inside:{"attribute-content":{pattern:/^(#\[)[\s\S]+(?=]$)/,lookbehind:!0,inside:{comment:e,string:r,"attribute-class-name":[{pattern:/([^:]|^)\b[a-z_]\w*(?!\\)\b/i,alias:"class-name",greedy:!0,lookbehind:!0},{pattern:/([^:]|^)(?:\\?\b[a-z_]\w*)+/i,alias:["class-name","class-name-fully-qualified"],greedy:!0,lookbehind:!0,inside:{punctuation:/\\/}}],constant:t,number:i,operator:n,punctuation:s}},delimiter:{pattern:/^#\[|]$/,alias:"punctuation"}}}}),a.hooks.add("before-tokenize",function(e){if(/<\?/.test(e.code)){a.languages["markup-templating"].buildPlaceholders(e,"php",/<\?(?:[^"'/#]|\/(?![*/])|("|')(?:\\[\s\S]|(?!\1)[^\\])*\1|(?:\/\/|#(?!\[))(?:[^?\n\r]|\?(?!>))*(?=$|\?>|[\r\n])|#\[|\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$))*?(?:\?>|$)/gi)}}),a.hooks.add("after-tokenize",function(e){a.languages["markup-templating"].tokenizePlaceholders(e,"php")})}(Prism); +!function(p){var a=p.languages.javadoclike={parameter:{pattern:/(^\s*(?:\/{3}|\*|\/\*\*)\s*@(?:param|arg|arguments)\s+)\w+/m,lookbehind:!0},keyword:{pattern:/(^\s*(?:\/{3}|\*|\/\*\*)\s*|\{)@[a-z][a-zA-Z-]+\b/m,lookbehind:!0},punctuation:/[{}]/};Object.defineProperty(a,"addSupport",{value:function(a,e){"string"==typeof a&&(a=[a]),a.forEach(function(a){!function(a,e){var n="doc-comment",t=p.languages[a];if(t){var r=t[n];if(!r){var o={"doc-comment":{pattern:/(^|[^\\])\/\*\*[^/][\s\S]*?(?:\*\/|$)/,lookbehind:!0,alias:"comment"}};r=(t=p.languages.insertBefore(a,"comment",o))[n]}if(r instanceof RegExp&&(r=t[n]={pattern:r}),Array.isArray(r))for(var i=0,s=r.length;i|(?:[a-zA-Z\d-]*!)?[\w\-%#;/?:@&=+$.~*'()]+)?/,t="(?:"+r.source+"(?:[ \t]+"+n.source+")?|"+n.source+"(?:[ \t]+"+r.source+")?)",a="(?:[^\\s\\x00-\\x08\\x0e-\\x1f!\"#%&'*,\\-:>?@[\\]`{|}\\x7f-\\x84\\x86-\\x9f\\ud800-\\udfff\\ufffe\\uffff]|[?:-])(?:[ \t]*(?:(?![#:])|:))*".replace(//g,function(){return"[^\\s\\x00-\\x08\\x0e-\\x1f,[\\]{}\\x7f-\\x84\\x86-\\x9f\\ud800-\\udfff\\ufffe\\uffff]"}),d="\"(?:[^\"\\\\\r\n]|\\\\.)*\"|'(?:[^'\\\\\r\n]|\\\\.)*'";function o(e,n){n=(n||"").replace(/m/g,"")+"m";var r="([:\\-,[{]\\s*(?:\\s<>[ \t]+)?)(?:<>)(?=[ \t]*(?:$|,|]|}|(?:[\r\n]\\s*)?#))".replace(/<>/g,function(){return t}).replace(/<>/g,function(){return e});return RegExp(r,n)}e.languages.yaml={scalar:{pattern:RegExp("([\\-:]\\s*(?:\\s<>[ \t]+)?[|>])[ \t]*(?:((?:\r?\n|\r)[ \t]+)\\S[^\r\n]*(?:\\2[^\r\n]+)*)".replace(/<>/g,function(){return t})),lookbehind:!0,alias:"string"},comment:/#.*/,key:{pattern:RegExp("((?:^|[:\\-,[{\r\n?])[ \t]*(?:<>[ \t]+)?)<>(?=\\s*:\\s)".replace(/<>/g,function(){return t}).replace(/<>/g,function(){return"(?:"+a+"|"+d+")"})),lookbehind:!0,greedy:!0,alias:"atrule"},directive:{pattern:/(^[ \t]*)%.+/m,lookbehind:!0,alias:"important"},datetime:{pattern:o("\\d{4}-\\d\\d?-\\d\\d?(?:[tT]|[ \t]+)\\d\\d?:\\d{2}:\\d{2}(?:\\.\\d*)?(?:[ \t]*(?:Z|[-+]\\d\\d?(?::\\d{2})?))?|\\d{4}-\\d{2}-\\d{2}|\\d\\d?:\\d{2}(?::\\d{2}(?:\\.\\d*)?)?"),lookbehind:!0,alias:"number"},boolean:{pattern:o("true|false","i"),lookbehind:!0,alias:"important"},null:{pattern:o("null|~","i"),lookbehind:!0,alias:"important"},string:{pattern:o(d),lookbehind:!0,greedy:!0},number:{pattern:o("[+-]?(?:0x[\\da-f]+|0o[0-7]+|(?:\\d+(?:\\.\\d*)?|\\.?\\d+)(?:e[+-]?\\d+)?|\\.inf|\\.nan)","i"),lookbehind:!0},tag:r,important:n,punctuation:/---|[:[\]{}\-,|>?]|\.\.\./},e.languages.yml=e.languages.yaml}(Prism); diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 06b24c8f..08fedf2d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,3 +16,36 @@ When a feature should be deprecated, or when you have a breaking change for a fu You can check which deprecation notice is triggered in tests * `make shell` * `SYMFONY_DEPRECATIONS_HELPER=0 ./vendor/bin/phpunit` + +## Task and transformer documentation + +Please use the following normalized PHPDoc template on every task and transformer (remove every item not needed). + +```php +/** + * Task summary (one line) + * + * Task description (multiple line, markdown, optional) + * + * ##### Task or Transformer reference + * + * * **Service**: `CleverAge\ProcessBundle\Path\To\Task\Class` + * * **code**: `transformer_code` + * * **Iterable task** + * * **Blocking task** + * * **Flushable task** + * * **Input**: `type`, description + * * **Output**: `type`, description + * + * ##### Options + * + * * `code` (`type`, _required_, _defaults to_ `value`): description + * + * @example "Resources/examples/path/to/file.yaml" description + * + * @author Your Name + */ +``` + +On public methods internal to the Process Bundle interfaces, please add `{@inheritDoc}` and `@internal`. +This is to avoid useless cluttering in the class description page. diff --git a/Configuration/ProcessConfiguration.php b/Configuration/ProcessConfiguration.php index f196c353..328e32a0 100644 --- a/Configuration/ProcessConfiguration.php +++ b/Configuration/ProcessConfiguration.php @@ -16,6 +16,8 @@ /** * Holds the processes configuration to launch a task * + * @internal + * * @author Valentin Clavreul * @author Vincent Chalnot */ diff --git a/Configuration/TaskConfiguration.php b/Configuration/TaskConfiguration.php index 8644174b..02b54d44 100644 --- a/Configuration/TaskConfiguration.php +++ b/Configuration/TaskConfiguration.php @@ -17,6 +17,8 @@ /** * Represents a task configuration inside a process * + * @internal + * * @author Valentin Clavreul * @author Vincent Chalnot */ diff --git a/Context/ContextualOptionResolver.php b/Context/ContextualOptionResolver.php index c0871ebb..f9baacba 100644 --- a/Context/ContextualOptionResolver.php +++ b/Context/ContextualOptionResolver.php @@ -13,6 +13,8 @@ /** * Class ContextualOptionResolver * + * @internal + * * @author Valentin Clavreul * @author Madeline Veyrenc */ diff --git a/DependencyInjection/CleverAgeProcessExtension.php b/DependencyInjection/CleverAgeProcessExtension.php index c84ef9c5..59cb4500 100644 --- a/DependencyInjection/CleverAgeProcessExtension.php +++ b/DependencyInjection/CleverAgeProcessExtension.php @@ -23,6 +23,8 @@ /** * This is the class that loads and manages your bundle configuration. * + * @internal + * * @see http://symfony.com/doc/current/cookbook/bundles/extension.html * * @author Valentin Clavreul diff --git a/DependencyInjection/Compiler/CheckSerializerCompilerPass.php b/DependencyInjection/Compiler/CheckSerializerCompilerPass.php index 6945f68e..f8bdc30d 100644 --- a/DependencyInjection/Compiler/CheckSerializerCompilerPass.php +++ b/DependencyInjection/Compiler/CheckSerializerCompilerPass.php @@ -18,6 +18,8 @@ /** * Check the presence of the serializer (required for this bundle), and help the user to set it * + * @internal + * * @author Valentin Clavreul */ class CheckSerializerCompilerPass implements CompilerPassInterface diff --git a/DependencyInjection/Compiler/RegistryCompilerPass.php b/DependencyInjection/Compiler/RegistryCompilerPass.php index 99ec2a2d..43ef7737 100644 --- a/DependencyInjection/Compiler/RegistryCompilerPass.php +++ b/DependencyInjection/Compiler/RegistryCompilerPass.php @@ -19,6 +19,8 @@ /** * Generic compiler pass to add tagged services to a registry * + * @internal + * * @author Valentin Clavreul * @author Vincent Chalnot */ diff --git a/DependencyInjection/Configuration.php b/DependencyInjection/Configuration.php index e5be1694..e17d70a5 100644 --- a/DependencyInjection/Configuration.php +++ b/DependencyInjection/Configuration.php @@ -23,6 +23,8 @@ * * To learn more see {@link http://symfony.com/doc/current/cookbook/bundles/configuration.html} * + * @internal + * * @author Valentin Clavreul * @author Vincent Chalnot */ diff --git a/Dockerfile b/Dockerfile index e971b585..f8e1a19a 100644 --- a/Dockerfile +++ b/Dockerfile @@ -37,3 +37,7 @@ COPY Resources/tests/environment/${SF_ENV} /app/ # Drop the process-bundle sources into this folder RUN mkdir /src-cleverage_process + +# PHP Documentor +RUN curl -o /bin/phpdoc -L https://github.com/phpDocumentor/phpDocumentor/releases/download/v3.0.0/phpDocumentor.phar +RUN chmod +x /bin/phpdoc diff --git a/EventDispatcher/BackcompatEventDispatcher.php b/EventDispatcher/BackcompatEventDispatcher.php index 0ad4b25f..1eba73bc 100644 --- a/EventDispatcher/BackcompatEventDispatcher.php +++ b/EventDispatcher/BackcompatEventDispatcher.php @@ -18,6 +18,8 @@ * A dispatcher that is flexible enough to handle every sf version * We use the PSR interface that is more simple, since PHP allow this kind of override * + * @internal + * * @deprecated once sf3.4 is fully dropped, only "ContractsEventDispatcherInterface" should be used * @author Fabien Salles */ diff --git a/EventListener/DataQueueEventListener.php b/EventListener/DataQueueEventListener.php index fb59f0e7..bc6bcb4a 100644 --- a/EventListener/DataQueueEventListener.php +++ b/EventListener/DataQueueEventListener.php @@ -17,6 +17,8 @@ * This is a basic queue, mainly aiming to catch data coming out of a process * Used mostly for testing purpose * + * @internal + * * @author Valentin Clavreul */ class DataQueueEventListener diff --git a/Exception/MultiBranchProcessException.php b/Exception/MultiBranchProcessException.php index d7bd67c1..beff3ed2 100644 --- a/Exception/MultiBranchProcessException.php +++ b/Exception/MultiBranchProcessException.php @@ -13,7 +13,7 @@ /** * Thrown when multiple independent branches are found in a process * - * @deprecated, we won't send an error for now + * @deprecated we won't send an error for now */ class MultiBranchProcessException extends \UnexpectedValueException implements ProcessExceptionInterface { diff --git a/ExpressionLanguage/PhpFunctionProvider.php b/ExpressionLanguage/PhpFunctionProvider.php index e994b1df..72220c16 100644 --- a/ExpressionLanguage/PhpFunctionProvider.php +++ b/ExpressionLanguage/PhpFunctionProvider.php @@ -16,6 +16,8 @@ /** * Allow to inject a set of PHP function into an ExpressionLanguage instance * + * @internal + * * @author Valentin Clavreul */ class PhpFunctionProvider implements ExpressionFunctionProviderInterface diff --git a/Logger/AbstractLogger.php b/Logger/AbstractLogger.php index fca21ddc..1fe4955f 100644 --- a/Logger/AbstractLogger.php +++ b/Logger/AbstractLogger.php @@ -17,6 +17,8 @@ * Base logic for logger tasks, see inherited services for more information * * Used for simplified autowiring + * + * @internal */ abstract class AbstractLogger extends BaseAbstractLogger { diff --git a/Logger/AbstractProcessor.php b/Logger/AbstractProcessor.php index 6145f0b5..4ba8f6b9 100644 --- a/Logger/AbstractProcessor.php +++ b/Logger/AbstractProcessor.php @@ -14,6 +14,8 @@ /** * @author Madeline Veyrenc + * + * @internal */ class AbstractProcessor { diff --git a/Logger/ProcessLogger.php b/Logger/ProcessLogger.php index 0ce95d3c..07f72a7a 100644 --- a/Logger/ProcessLogger.php +++ b/Logger/ProcessLogger.php @@ -12,6 +12,8 @@ /** * @author Madeline Veyrenc + * + * @internal */ class ProcessLogger extends AbstractLogger { diff --git a/Logger/ProcessProcessor.php b/Logger/ProcessProcessor.php index 5337fabc..2c9098df 100644 --- a/Logger/ProcessProcessor.php +++ b/Logger/ProcessProcessor.php @@ -13,7 +13,8 @@ /** * Class ProcessProcessor * - * @package CleverAge\ProcessBundle\Logger + * @internal + * * @author Madeline Veyrenc */ class ProcessProcessor extends AbstractProcessor diff --git a/Logger/TaskLogger.php b/Logger/TaskLogger.php index e0248c40..42e17ad9 100644 --- a/Logger/TaskLogger.php +++ b/Logger/TaskLogger.php @@ -13,7 +13,8 @@ /** * Class TaskLogger * - * @package CleverAge\ProcessBundle\Logger + * @internal + * * @author Madeline Veyrenc */ class TaskLogger extends AbstractLogger diff --git a/Logger/TaskProcessor.php b/Logger/TaskProcessor.php index 09b2090c..893b41cb 100644 --- a/Logger/TaskProcessor.php +++ b/Logger/TaskProcessor.php @@ -13,7 +13,7 @@ /** * Class TaskProcessor * - * @package CleverAge\ProcessBundle\Logger + * @internal * @author Madeline Veyrenc */ class TaskProcessor extends AbstractProcessor diff --git a/Logger/TransformerProcessor.php b/Logger/TransformerProcessor.php index e26af43f..78f831b0 100644 --- a/Logger/TransformerProcessor.php +++ b/Logger/TransformerProcessor.php @@ -13,7 +13,7 @@ /** * Class TransformerProcessor * - * @package CleverAge\ProcessBundle\Logger + * @internal * @author Madeline Veyrenc */ class TransformerProcessor extends AbstractProcessor diff --git a/Makefile b/Makefile index 4204d451..31b92c79 100644 --- a/Makefile +++ b/Makefile @@ -68,3 +68,8 @@ vendor/%: docker container create --name cleverage_process_bundle_tmp cleverage/process-bundle:$(@F) docker cp cleverage_process_bundle_tmp:/app/vendor vendor-$(@F) docker container rm cleverage_process_bundle_tmp + +doc: + $(DOCKER_RUN) -w /src-cleverage_process cleverage/process-bundle:$(SF_ENV) phpdoc + $(DOCKER_RUN) -w /src-cleverage_process -u root cleverage/process-bundle:$(SF_ENV) chown -R $(shell id -u) var/doc .phpdoc + @echo "The phpdoc has been generated, you can see it at file://$$(realpath var/doc/index.html)" diff --git a/Model/AbstractConfigurableTask.php b/Model/AbstractConfigurableTask.php index 3a7e7d62..7524816b 100644 --- a/Model/AbstractConfigurableTask.php +++ b/Model/AbstractConfigurableTask.php @@ -27,9 +27,9 @@ abstract class AbstractConfigurableTask implements InitializableTaskInterface /** * Only validate the options at initialization, ensuring that the task will not fail at runtime * - * @param ProcessState $state + * {@inheritDoc} * - * @throws ExceptionInterface + * @internal */ public function initialize(ProcessState $state) { diff --git a/Model/ProcessHistory.php b/Model/ProcessHistory.php index 66aadf82..ea3475e1 100644 --- a/Model/ProcessHistory.php +++ b/Model/ProcessHistory.php @@ -15,6 +15,8 @@ /** * Logs information about a process * + * @deprecated not used anymore, will be removed in v4.0 + * * @author Valentin Clavreul * @author Vincent Chalnot */ diff --git a/Model/SubprocessInstance.php b/Model/SubprocessInstance.php index 839147de..2cdc41ce 100644 --- a/Model/SubprocessInstance.php +++ b/Model/SubprocessInstance.php @@ -16,6 +16,9 @@ use Symfony\Component\Process\PhpExecutableFinder; use Symfony\Component\Process\Process; +/** + * @internal + */ class SubprocessInstance { public const OPTION_JSON_BUFFERING = 'json-buffering'; diff --git a/Model/TaskInterface.php b/Model/TaskInterface.php index 8248892a..ab1e7a32 100644 --- a/Model/TaskInterface.php +++ b/Model/TaskInterface.php @@ -23,6 +23,8 @@ interface TaskInterface { /** * @param ProcessState $state + * + * @internal */ public function execute(ProcessState $state); } diff --git a/Resources/examples/task/abstract_iterable_output_task.php b/Resources/examples/task/abstract_iterable_output_task.php new file mode 100644 index 00000000..d0a26157 --- /dev/null +++ b/Resources/examples/task/abstract_iterable_output_task.php @@ -0,0 +1,19 @@ +getInput(); + + // Do something with data that will produce an array + // For example, data might be a code and you can fetch a collection in database + $array = $data; + + // `\ArrayIterator` is the most simple iterator, but it loads everything in memory + return new \ArrayIterator($array); + } +} diff --git a/Resources/examples/task/column_aggregator_task.yaml b/Resources/examples/task/column_aggregator_task.yaml new file mode 100644 index 00000000..026b0b54 --- /dev/null +++ b/Resources/examples/task/column_aggregator_task.yaml @@ -0,0 +1,9 @@ +# Task configuration level +sort_item_by_familly: + service: '@CleverAge\ProcessBundle\Task\ColumnAggregatorTask' + options: + columns: '%family_names%' # A big array with a list of families + ignore_missing: true # Only a warning if there is a missing column + condition: + match: + '[input_column_value]': 'X' # Looks for every "X" family by family diff --git a/Resources/examples/task/file/xml/xml_reader_task.yaml b/Resources/examples/task/file/xml/xml_reader_task.yaml new file mode 100644 index 00000000..6371d4f0 --- /dev/null +++ b/Resources/examples/task/file/xml/xml_reader_task.yaml @@ -0,0 +1,5 @@ +# Task configuration level +my_xml_reader: + service: '@CleverAge\ProcessBundle\Task\File\Xml\XmlReaderTask' + options: + file_path: '%kernel.project_dir%/var/data/file.xml' diff --git a/Resources/examples/task/file/xml/xml_writer_task.yaml b/Resources/examples/task/file/xml/xml_writer_task.yaml new file mode 100644 index 00000000..1ac3a765 --- /dev/null +++ b/Resources/examples/task/file/xml/xml_writer_task.yaml @@ -0,0 +1,5 @@ +# Task configuration level +my_xml_writer: + service: '@CleverAge\ProcessBundle\Task\File\Xml\XmlWriterTask' + options: + file_path: '%kernel.project_dir%/var/data/file.xml' diff --git a/Resources/examples/task/row_aggregator_task.yaml b/Resources/examples/task/row_aggregator_task.yaml new file mode 100644 index 00000000..28715cc8 --- /dev/null +++ b/Resources/examples/task/row_aggregator_task.yaml @@ -0,0 +1,31 @@ +# Example input +data_in: + - {code: item_1, attribute1: val1, attribute2: b} + - {code: item_2, attribute1: val1, attribute2: c} + - {code: item_3, attribute1: val1, attribute2: d} + - {code: item_4, attribute1: val2, attribute2: e} + +--- + +# Task configuration level +aggregate_rows: + service: '@CleverAge\ProcessBundle\Task\RowAggregatorTask' + options: + aggregate_by: attribute1 + aggregation_key: values + aggregate_columns: [code] + +--- + +# Output +data_out: + val1: + attribute2: b # Other values are ignored + values: + - { code: item_1 } + - { code: item_2 } + - { code: item_3 } + val2: + attribute2: e + values: + - { code: item_4 } diff --git a/Task/AbstractIterableOutputTask.php b/Task/AbstractIterableOutputTask.php index bf177af3..642cc720 100644 --- a/Task/AbstractIterableOutputTask.php +++ b/Task/AbstractIterableOutputTask.php @@ -20,6 +20,15 @@ /** * Base class to handle output iterations * + * Extends this class and implement `initializeIterator()` to provide data that will be iterated upon. + * + * ##### Task reference + * + * * **Abstract task** + * * **Iterable task** + * + * @example "Resources/examples/task/abstract_iterable_output_task.php" A simple implementation + * * @author Valentin Clavreul * @author Vincent Chalnot */ @@ -29,10 +38,9 @@ abstract class AbstractIterableOutputTask extends AbstractConfigurableTask imple protected $iterator; /** - * @param ProcessState $state + * {@inheritDoc} * - * @throws \InvalidArgumentException - * @throws ExceptionInterface + * @internal */ public function execute(ProcessState $state) { @@ -49,13 +57,9 @@ public function execute(ProcessState $state) } /** - * Moves the internal pointer to the next element, - * return true if the task has a next element - * return false if the task has terminated it's iteration - * - * @param ProcessState $state + * {@inheritDoc} * - * @return bool + * @internal */ public function next(ProcessState $state) { diff --git a/Task/AggregateIterableTask.php b/Task/AggregateIterableTask.php index df6a2e39..dc843329 100644 --- a/Task/AggregateIterableTask.php +++ b/Task/AggregateIterableTask.php @@ -12,13 +12,19 @@ use CleverAge\ProcessBundle\Model\BlockingTaskInterface; use CleverAge\ProcessBundle\Model\ProcessState; +use CleverAge\ProcessBundle\Model\TaskInterface; use Symfony\Component\OptionsResolver\Exception\ExceptionInterface; /** - * Class AggregateIterableTask - * * Aggregate the result of iterable tasks in an array * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\AggregateIterableTask` + * * **Blocking task** + * * **Input**: `any` + * * **Output**: `array`, of received inputs + * * @author Madeline Veyrenc */ class AggregateIterableTask implements BlockingTaskInterface @@ -27,9 +33,9 @@ class AggregateIterableTask implements BlockingTaskInterface protected $result = []; /** - * @param ProcessState $state + * {@inheritDoc} * - * @throws ExceptionInterface + * @internal */ public function execute(ProcessState $state) { @@ -37,7 +43,9 @@ public function execute(ProcessState $state) } /** - * @param ProcessState $state + * {@inheritDoc} + * + * @internal */ public function proceed(ProcessState $state) { diff --git a/Task/ArrayMergeTask.php b/Task/ArrayMergeTask.php index a4a11b85..d645ea37 100644 --- a/Task/ArrayMergeTask.php +++ b/Task/ArrayMergeTask.php @@ -17,6 +17,20 @@ /** * Merge every input array, and return the result + * + * By default, behaves exactly like [`array_merge`](https://www.php.net/manual/en/function.array-merge.php), but it can be changed to any other function with similar algorithm. + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\ArrayMergeTask` + * * **Blocking task** + * * **Input**: `array` + * * **Output**: `array`, or any output type from the merge callback + * + * ##### Options + * + * * `merge_function` (`string`, _defaults to_ `array_merge`): must be one of the 4 PHP merge function ([`array_merge`](https://www.php.net/manual/en/function.array-merge.php), [`array_merge_recursive`](https://www.php.net/manual/en/function.array-merge-recursive.php), [`array_replace`](https://www.php.net/manual/en/function.array-replace.php), or [`array_replace_recursive`](https://www.php.net/manual/en/function.array-replace-recursive.php)) + * */ class ArrayMergeTask extends AbstractConfigurableTask implements BlockingTaskInterface { diff --git a/Task/ColumnAggregatorTask.php b/Task/ColumnAggregatorTask.php index e6351ae4..3498a958 100644 --- a/Task/ColumnAggregatorTask.php +++ b/Task/ColumnAggregatorTask.php @@ -19,7 +19,47 @@ use Symfony\Component\PropertyAccess\PropertyAccessorInterface; /** - * @todo @vclavreul describe this task + * Takes a list of item, and group them depending on a defined condition for a set of columns. + * + * This task allows to "flip" a matrix. + * It will create one group per given column, and for each row, add the input to the group it matches. + * + * The main use case was to invert a table like + * ``` + * |code |val1|val2| + * |item1| X | X | + * |item2| | X | + * |item3| X | | + * ``` + * + * And get a list like + * * `val1 => [item1, item3]` + * * `val2 => [item1, item2]` + * + * See {@see \CleverAge\ProcessBundle\Tests\Task\ColumnAggregatorTaskTest} for input and output values of the example + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\ColumnAggregatorTask` + * * **Blocking task** + * * **Input**: `array` + * * **Output**: `array` of `array`, each one containing + * - the key defined by the `reference_key` option, where the value is a column name + * - the key defined by the `aggregation_key` option, where the value is the list of matching inputs + * + * ##### Options + * + * * `columns` (`array`, _required_): the list of columns that will be used to group the values + * * `reference_key` (`string`, _defaults to_ `column`): the key in the output that will contain the column name + * * `aggregation_key` (`string`, _defaults to_ `values`): the key in the output that will contain the list of matching values + * * `condition` (_defaults to_ `[]`): a condition to aggregate value, see {@see \CleverAge\ProcessBundle\Transformer\ConditionTrait} for details. + * The item that will be tested is an array containing + * - `input_column_value` : the value of the current row for one of the columns + * - `input` : the full current row + * * `ignore_missing` (`boolean`, _defaults to_ `false`): if false, triggers an error if a column is not in the input + * + * @example "Resources/examples/task/column_aggregator_task.yaml" Simple use case + * @example "Resources/tests/task/column_aggregator_task.yml" Full test case * * @author Valentin Clavreul */ diff --git a/Task/ConstantIterableOutputTask.php b/Task/ConstantIterableOutputTask.php index 9c744c17..30bf2ce3 100644 --- a/Task/ConstantIterableOutputTask.php +++ b/Task/ConstantIterableOutputTask.php @@ -17,7 +17,22 @@ use Symfony\Component\OptionsResolver\OptionsResolver; /** - * Always send the same output regardless of the input, only accepts array for values and iterate over it + * Iterate over a static pre-defined set of values. + * + * Always send the same output regardless of the input, only accepts array for values and iterate over it. + * + * Same as {@see ConstantOutputTask} iterate over values. + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\ConstantIterableOutputTask` + * * **Iterable task** + * * **Input**: _ignored_ + * * **Output**: `any`, values from the `output` option + * + * ##### Options + * + * * **`output`** (`array`, _required_): Array of values to iterate onto * * @author Valentin Clavreul * @author Vincent Chalnot @@ -25,10 +40,9 @@ class ConstantIterableOutputTask extends AbstractIterableOutputTask { /** - * @param OptionsResolver $resolver + * {@inheritDoc} * - * @throws AccessException - * @throws UndefinedOptionsException + * @internal */ protected function configureOptions(OptionsResolver $resolver) { diff --git a/Task/ConstantOutputTask.php b/Task/ConstantOutputTask.php index 9017e708..844d4d16 100644 --- a/Task/ConstantOutputTask.php +++ b/Task/ConstantOutputTask.php @@ -17,7 +17,19 @@ use Symfony\Component\OptionsResolver\OptionsResolver; /** - * Always send the same output regardless of the input + * Outputs a static pre-defined value + * + * Simply outputs the same configured value all the time, ignores any input + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\ConstantOutputTask` + * * **Input**: _ignored_ + * * **Output**: `any`, value from the `output` option + * + * ##### Options + * + * * `output` (_required_): Value to output * * @author Valentin Clavreul * @author Vincent Chalnot @@ -25,10 +37,9 @@ class ConstantOutputTask extends AbstractConfigurableTask { /** - * @param ProcessState $state + * {@inheritDoc} * - * @throws \InvalidArgumentException - * @throws ExceptionInterface + * @internal */ public function execute(ProcessState $state) { @@ -36,9 +47,9 @@ public function execute(ProcessState $state) } /** - * @param OptionsResolver $resolver + * {@inheritDoc} * - * @throws AccessException + * @internal */ protected function configureOptions(OptionsResolver $resolver) { diff --git a/Task/CounterTask.php b/Task/CounterTask.php index 1726432f..830e3e9f 100644 --- a/Task/CounterTask.php +++ b/Task/CounterTask.php @@ -16,8 +16,24 @@ use Symfony\Component\OptionsResolver\OptionsResolver; /** + * Outputs periodically the number of time this task is called. + * * Count the number of times the task is processed and continue every N iteration (skip the rest of the time) - * Flush at the end with the actual count + * Flush at the end with the actual count. + * + * It can be useful for batch like workflow. + * See also {@see IterableBatchTask}. + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\CounterTask` + * * **Flushable task** + * * **Input**: _ignored_ + * * **Output**: `int`, the number of time this task is called + * + * ##### Options + * + * * `flush_every` (`int`, _required_): the period at which the task will produce outputs * * @author Vincent Chalnot */ diff --git a/Task/Debug/DebugTask.php b/Task/Debug/DebugTask.php index 58791d56..1bca2df2 100644 --- a/Task/Debug/DebugTask.php +++ b/Task/Debug/DebugTask.php @@ -17,13 +17,24 @@ /** * Dump the content of the input * + * Dumps the input value to the console, obviously for debug purposes. + * Only usable in dev environment (where the [VarDumper Component](https://symfony.com/doc/current/components/var_dumper.html) is enabled) + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\Debug\DebugTask` + * * **Input**: `any` + * * **Output**: `any`, re-output given input + * * @author Valentin Clavreul * @author Vincent Chalnot */ class DebugTask implements TaskInterface { /** - * @param ProcessState $state + * {@inheritDoc} + * + * @internal */ public function execute(ProcessState $state) { diff --git a/Task/DummyTask.php b/Task/DummyTask.php index c5e2e655..f1605e32 100644 --- a/Task/DummyTask.php +++ b/Task/DummyTask.php @@ -16,13 +16,23 @@ /** * Dummy task that pass the input to the output * + * Passes the input to the output, can be used as an entry point allow multiple tasks to be run at the entry point + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\Debug\DummyTask` + * * **Input**: `any` + * * **Output**: `any`, re-output given input + * * @author Valentin Clavreul * @author Vincent Chalnot */ class DummyTask implements TaskInterface { /** - * @param ProcessState $state + * {@inheritDoc} + * + * @internal */ public function execute(ProcessState $state) { diff --git a/Task/Event/EventDispatcherTask.php b/Task/Event/EventDispatcherTask.php index 0a43cafd..24e10186 100644 --- a/Task/Event/EventDispatcherTask.php +++ b/Task/Event/EventDispatcherTask.php @@ -21,8 +21,22 @@ /** * Call the Symfony event dispatcher + * * If defined as passive (which is the default), it automatically set the output from the input - * + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\Event\EventDispatcherTask` + * * **Input**: `any` + * * **Output**: + * - `any` when `passive` option is set to true + * - `null` in other cases + * + * ##### Options + * + * * `event_name` (`string`, _required_): Format for normalization ("json", "xml", ... an empty string should also work) + * * `passive` (`bool`, _defaults to_ `true`): Pass input to output + * * @author Valentin Clavreul * @author Vincent Chalnot * @author Madeline Veyrenc @@ -33,7 +47,7 @@ class EventDispatcherTask extends AbstractConfigurableTask protected $eventDispatcher; /** - * @param EventDispatcherInterface $eventDispatcher + * @internal */ public function __construct(EventDispatcherInterface $eventDispatcher) { @@ -41,9 +55,9 @@ public function __construct(EventDispatcherInterface $eventDispatcher) } /** - * @param ProcessState $state + * {@inheritDoc} * - * @throws ExceptionInterface + * @internal */ public function execute(ProcessState $state) { @@ -58,10 +72,9 @@ public function execute(ProcessState $state) } /** - * @param OptionsResolver $resolver + * {@inheritDoc} * - * @throws AccessException - * @throws UndefinedOptionsException + * @internal */ protected function configureOptions(OptionsResolver $resolver) { diff --git a/Task/File/Csv/AbstractCsvResourceTask.php b/Task/File/Csv/AbstractCsvResourceTask.php index 292b1672..034f8f71 100644 --- a/Task/File/Csv/AbstractCsvResourceTask.php +++ b/Task/File/Csv/AbstractCsvResourceTask.php @@ -31,7 +31,9 @@ abstract class AbstractCsvResourceTask extends AbstractConfigurableTask implemen protected $csv; /** - * @param ProcessState $state + * {@inheritDoc} + * + * @internal */ public function finalize(ProcessState $state) { diff --git a/Task/File/Csv/CsvReaderTask.php b/Task/File/Csv/CsvReaderTask.php index 68f363c5..d1cfb984 100644 --- a/Task/File/Csv/CsvReaderTask.php +++ b/Task/File/Csv/CsvReaderTask.php @@ -20,8 +20,29 @@ use Symfony\Component\OptionsResolver\OptionsResolver; /** - * Reads the file path from configuration and iterates over it - * Ignores any input + * Iterates over a CSV file. + * + * + * Reads a CSV file and iterate on each line, returning an array of key -> values. Skips empty lines. Ignores any input. + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\File\Csv\CsvReaderTask` + * * **Iterable task** + * * **Input**: _ignored_ + * * **Output**: `array`, foreach line, it will return a php array where key comes from headers and values are strings. + * Underlying method is [fgetcsv](https://secure.php.net/manual/en/function.fgetcsv.php). + * + * ##### Options + * + * * `file_path` (`string`, _required_): Path of the file to read from (relative to symfony root or absolute) + * * `delimiter` (`string`, _defaults to_ `;`): CSV delimiter + * * `enclosure` (`string`, _defaults to_ `"`): CSV enclosure character + * * `escape` (`string`, _defaults to_ `\\`): CSV escape character + * * `headers` (`array|null`, _defaults to_ `null`): Static list of CSV headers, without the option, it will be dynamically read from first input + * * `mode` (`string`, _defaults to_ `rb`): File open mode (see [fopen mode parameter](https://secure.php.net/manual/en/function.fopen.php)) + * * `log_empty_lines` (`bool`, _defaults to_ `false`): Log when the output is empty + * * * @author Valentin Clavreul * @author Vincent Chalnot @@ -32,7 +53,7 @@ class CsvReaderTask extends AbstractCsvTask implements IterableTaskInterface protected $logger; /** - * @param LoggerInterface $logger + * @internal */ public function __construct(LoggerInterface $logger) { @@ -40,13 +61,9 @@ public function __construct(LoggerInterface $logger) } /** - * @param ProcessState $state + * {@inheritDoc} * - * @throws \UnexpectedValueException - * @throws \RuntimeException - * @throws \InvalidArgumentException - * @throws ExceptionInterface - * @throws \LogicException + * @internal */ public function execute(ProcessState $state) { @@ -80,17 +97,9 @@ public function execute(ProcessState $state) } /** - * Moves the internal pointer to the next element, - * return true if the task has a next element - * return false if the task has terminated it's iteration - * - * @param ProcessState $state - * - * @throws \LogicException - * @throws \UnexpectedValueException - * @throws \RuntimeException + * {@inheritDoc} * - * @return bool + * @internal */ public function next(ProcessState $state) { diff --git a/Task/File/Csv/CsvWriterTask.php b/Task/File/Csv/CsvWriterTask.php index 9f29c17b..1b075c3c 100644 --- a/Task/File/Csv/CsvWriterTask.php +++ b/Task/File/Csv/CsvWriterTask.php @@ -20,23 +20,37 @@ use Symfony\Component\OptionsResolver\OptionsResolver; /** - * Reads the file path from configuration and iterates over it - * Ignores any input + * Writes all incoming data to a CSV file, outputting it's path when over + * + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\File\Csv\CsvWriterTask` + * * **Blocking task** + * * **Input**: `array`, foreach line, it will need a php array where key match the headers and values are convertible to string. + * Underlying method is [fputcsv](https://secure.php.net/manual/en/function.fputcsv.php). + * * **Output**: `string`, absolute path of the produced file + * + * ##### Options + * + * * `file_path` (`string`, _required_): Path of the file to write to (relative to symfony root or absolute). It can also take two placeholders (`{date}` and `{date_time}`) to insert timestamps into the filename + * * `delimiter` (`string`, _defaults to_ `;`): CSV delimiter + * * `enclosure` (`string`, _defaults to_ `"`): CSV enclosure character + * * `escape` (`string`, _defaults to_ `\\`): CSV escape character + * * `headers` (`array|null`, _defaults to_ `null`): `null` | Static list of CSV headers, without the option, it will be dynamically read from first line + * * `mode` (`string`, _defaults to_ `wb`): File open mode (see [fopen mode parameter](https://secure.php.net/manual/en/function.fopen.php)) + * * `split_character` (`string`, _defaults to_ `\|`): Used to implode array values + * * `write_headers` (`bool`, _defaults to_ `true`): Write the headers as a first line * * @author Valentin Clavreul * @author Vincent Chalnot - * - * @property CsvFile $csv */ class CsvWriterTask extends AbstractCsvTask implements BlockingTaskInterface { /** - * @param ProcessState $state + * {@inheritDoc} * - * @throws \RuntimeException - * @throws \UnexpectedValueException - * @throws \InvalidArgumentException - * @throws ExceptionInterface + * @internal */ public function execute(ProcessState $state) { @@ -50,7 +64,9 @@ public function execute(ProcessState $state) } /** - * @param ProcessState $state + * {@inheritDoc} + * + * @internal */ public function proceed(ProcessState $state) { @@ -60,10 +76,9 @@ public function proceed(ProcessState $state) } /** - * @param OptionsResolver $resolver + * {@inheritDoc} * - * @throws AccessException - * @throws UndefinedOptionsException + * @internal */ protected function configureOptions(OptionsResolver $resolver) { diff --git a/Task/File/Xml/XmlReaderTask.php b/Task/File/Xml/XmlReaderTask.php index 752a2e51..869430d1 100644 --- a/Task/File/Xml/XmlReaderTask.php +++ b/Task/File/Xml/XmlReaderTask.php @@ -19,6 +19,21 @@ /** * Read an XML file * + * Requires `php-xml`. + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\File\Xml\XmlReaderTask` + * * **Input**: _ignored_ + * * **Output**: `\DOMDocument`, built from the given file. + * + * ##### Options + * + * * `file_path` (`string`, _required_): Path of the file to read from (relative to symfony root or absolute) + * * `mode` (`string`,_defaults to_ `rb`): File open mode (see [fopen mode parameter](https://secure.php.net/manual/en/function.fopen.php)) + * + * @example "Resources/examples/task/file/xml/xml_reader_task.yaml" + * @author Valentin Clavreul */ class XmlReaderTask extends AbstractConfigurableTask @@ -27,9 +42,7 @@ class XmlReaderTask extends AbstractConfigurableTask protected $logger; /** - * XmlReaderTask constructor. - * - * @param LoggerInterface $logger + * @internal */ public function __construct(LoggerInterface $logger) { @@ -50,6 +63,8 @@ protected function configureOptions(OptionsResolver $resolver) /** * {@inheritDoc} + * + * @internal */ public function execute(ProcessState $state) { diff --git a/Task/File/Xml/XmlWriterTask.php b/Task/File/Xml/XmlWriterTask.php index f62b1f3c..6f0586f7 100644 --- a/Task/File/Xml/XmlWriterTask.php +++ b/Task/File/Xml/XmlWriterTask.php @@ -17,8 +17,22 @@ use Symfony\Component\OptionsResolver\OptionsResolver; /** - * Write an XML file + * Write data to an XML file + * + * Requires `php-xml`. * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\File\Xml\XmlWriterTask` + * * **Input**: `\DOMDocument` + * * **Output**: `string`, the resulting file path. + * + * ##### Options + * + * * `file_path` (`string`, _required_): Path of the file to write into (relative to symfony root or absolute) + * * `mode` (`string`, _defaults to_ `rb`): File open mode (see [fopen mode parameter](https://secure.php.net/manual/en/function.fopen.php)) + * + * @example "Resources/examples/task/file/xml/xml_writer_task.yaml" * @author Valentin Clavreul */ class XmlWriterTask extends AbstractConfigurableTask @@ -27,9 +41,7 @@ class XmlWriterTask extends AbstractConfigurableTask protected $logger; /** - * XmlReaderTask constructor. - * - * @param LoggerInterface $logger + * @internal */ public function __construct(LoggerInterface $logger) { @@ -38,6 +50,8 @@ public function __construct(LoggerInterface $logger) /** * {@inheritDoc} + * + * @internal */ protected function configureOptions(OptionsResolver $resolver) { @@ -50,6 +64,8 @@ protected function configureOptions(OptionsResolver $resolver) /** * {@inheritDoc} + * + * @internal */ public function execute(ProcessState $state) { diff --git a/Task/FilterTask.php b/Task/FilterTask.php index 23fcbcd1..848116b3 100644 --- a/Task/FilterTask.php +++ b/Task/FilterTask.php @@ -22,8 +22,22 @@ /** * Skip inputs under given matching conditions - * - equality is softly checked - * - unexisting key is the same as null + * + * Matching use the following rules + * * equality is softly checked + * * missing key is the same as `null` + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\FilterTask` + * * **Input**: `array` or `object` that can be used by the [PropertyAccess component](https://symfony.com/components/PropertyAccess) + * * **Output**: the same as input, unmodified + * + * ##### Options + * + * The list of options is the same than the {@see \CleverAge\ProcessBundle\Transformer\ConditionTrait}. + * + * @example "Resources/tests/task/filter_task.yml" Some basic examples */ class FilterTask extends AbstractConfigurableTask { @@ -32,6 +46,8 @@ class FilterTask extends AbstractConfigurableTask /** * {@inheritDoc} + * + * @internal */ public function initialize(ProcessState $state) { @@ -42,11 +58,7 @@ public function initialize(ProcessState $state) /** * {@inheritDoc} * - * @throws ExceptionInterface - * @throws UnexpectedTypeException - * @throws InvalidArgumentException - * @throws AccessException - * @throws \InvalidArgumentException + * @internal */ public function execute(ProcessState $state) { @@ -63,6 +75,8 @@ public function execute(ProcessState $state) /** * {@inheritDoc} + * + * @internal */ protected function configureOptions(OptionsResolver $resolver) { diff --git a/Task/GroupByAggregateIterableTask.php b/Task/GroupByAggregateIterableTask.php index c334cd11..74898f11 100644 --- a/Task/GroupByAggregateIterableTask.php +++ b/Task/GroupByAggregateIterableTask.php @@ -9,9 +9,24 @@ use Symfony\Component\PropertyAccess\PropertyAccessorInterface; /** + * Groups input, using some value as a unique key. + * * Attempt to aggregate inputs in an associative array with a key formed by configurable fields of the input. * This task could be used to remove duplicates from the aggregate. * + * The values from the options must be able to be converted to strings. The character `-` is used as a delimiter. + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\GroupByAggregateIterableTask` + * * **Blocking task** + * * **Input**: `array` or `object` that can be used by the [PropertyAccess component](https://symfony.com/components/PropertyAccess) + * * **Output**: `array` containing the list of unique input (last one wins) + * + * ##### Options + * + * * `group_by_accessors` (`type`, _required_, _defaults to_ `value`): description + * * @author Alix Mauro */ class GroupByAggregateIterableTask extends AbstractConfigurableTask implements BlockingTaskInterface @@ -26,7 +41,7 @@ class GroupByAggregateIterableTask extends AbstractConfigurableTask implements B protected $accessor; /** - * @param PropertyAccessorInterface $accessor + * @internal */ public function __construct(PropertyAccessorInterface $accessor) { @@ -36,6 +51,7 @@ public function __construct(PropertyAccessorInterface $accessor) /** * {@inheritDoc} + * @internal */ public function execute(ProcessState $state): void { @@ -61,6 +77,7 @@ public function execute(ProcessState $state): void /** * {@inheritDoc} + * @internal */ public function proceed(ProcessState $state): void { @@ -73,6 +90,7 @@ public function proceed(ProcessState $state): void /** * {@inheritDoc} + * @internal */ protected function configureOptions(OptionsResolver $resolver): void { diff --git a/Task/InputAggregatorTask.php b/Task/InputAggregatorTask.php index 001cb497..91a79ef3 100644 --- a/Task/InputAggregatorTask.php +++ b/Task/InputAggregatorTask.php @@ -18,10 +18,26 @@ use Symfony\Component\OptionsResolver\OptionsResolver; /** - * Wait for defined inputs before passing an aggregated output. - * Should have been a BlockingTask, but due to limitations in the current model, it's a hack using skips and finalize. + * Aggregates data from heterogeneous inputs. + * + * It skips output until input is received from every parent task. Then, the internal data is reset (except for `keep_inputs` indexes). + * + * Warning : the `clean_input_on_override` option can be dangerous if set to `false`. Especially in loops (iterable process), there can be cases where the inputs are mixed between the iterations of an input... (ex: one of the parent task has skipped output due to an error). Even on `true`, some case have been determined to be problematic. + * + * The usage of this task is therefore **strongly discouraged**, unless you are using it in a non-iterable process. It may one day evolve in a Blocking Task. + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\InputAggregatorTask` + * * **Input**: `any` + * * **Output**: `array`, list of index destination => values from previous tasks + * + * ##### Options + * + * * `input_codes` (`array`, _required_): List of task code => index destination + * * `clean_input_on_override` (`bool`, _defaults to_ `true`): Empty the future output if there any override + * * `keep_inputs` (`array` or `null`, _defaults to_ `null`): List of index * destination to keep on flush * - * @see README.md:Known issues * @deprecated It's way too much error prone - should be refactored as a blocking task */ class InputAggregatorTask extends AbstractConfigurableTask @@ -33,11 +49,9 @@ class InputAggregatorTask extends AbstractConfigurableTask * Store inputs and once everything has been received, pass to next task * Once an output has been generated this task is reset, and may wait for another loop * - * @param ProcessState $state + * {@inheritDoc} * - * @throws \UnexpectedValueException - * @throws \InvalidArgumentException - * @throws ExceptionInterface + * @internal */ public function execute(ProcessState $state) { @@ -75,10 +89,9 @@ public function execute(ProcessState $state) } /** - * @param OptionsResolver $resolver + * {@inheritDoc} * - * @throws AccessException - * @throws UndefinedOptionsException + * @internal */ protected function configureOptions(OptionsResolver $resolver) { diff --git a/Task/InputIteratorTask.php b/Task/InputIteratorTask.php index 97ee1ad9..92e8286e 100644 --- a/Task/InputIteratorTask.php +++ b/Task/InputIteratorTask.php @@ -15,14 +15,21 @@ use Symfony\Component\OptionsResolver\Exception\ExceptionInterface; /** - * Iterates from the input of the previous task + * Iterate on every value from given input + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\InputIteratorTask` + * * **Iterable task** + * * **Input**: `\Iterable` or `array`, an input to iterate onto + * * **Output**: `any`, each value from the iterable * * @author Madeline Veyrenc */ class InputIteratorTask extends AbstractIterableOutputTask { /** - * @inheritDoc + * {@inheritDoc} */ protected function initializeIterator(ProcessState $state): \Iterator { diff --git a/Task/IterableBatchTask.php b/Task/IterableBatchTask.php index 5335a0cb..f64a3c38 100644 --- a/Task/IterableBatchTask.php +++ b/Task/IterableBatchTask.php @@ -20,9 +20,23 @@ use Symfony\Component\OptionsResolver\OptionsResolver; /** - * A Batch task that iterate on flush - * It's mainly an example task since it's not useful as-is, but the processInput method may allow custom overrides + * Accumulate inputs and periodically flush them using iterations. + * + * A Batch task that iterate on flush. + * It's mainly an example task since it's not useful as-is, but the processInput method may allow custom overrides. * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\IterableBatchTask` + * * **Iterable task** + * * **Flushable task** + * * **Input**: `any` + * * **Output**: `any`, same type as input + * + * ##### Options + * + * * `batch_count` (`integer`, _defaults to_ `10`): Accumulated batch size + * * @author Valentin Clavreul */ class IterableBatchTask extends AbstractConfigurableTask implements FlushableTaskInterface, IterableTaskInterface @@ -38,9 +52,7 @@ class IterableBatchTask extends AbstractConfigurableTask implements FlushableTas protected $logger; /** - * IterableBatchTask constructor. - * - * @param LoggerInterface $logger + * @internal */ public function __construct(LoggerInterface $logger) { @@ -48,7 +60,9 @@ public function __construct(LoggerInterface $logger) } /** - * @param ProcessState $state + * {@inheritDoc} + * + * @internal */ public function initialize(ProcessState $state) { @@ -58,7 +72,9 @@ public function initialize(ProcessState $state) /** - * @param ProcessState $state + * {@inheritDoc} + * + * @internal */ public function flush(ProcessState $state) { @@ -71,10 +87,9 @@ public function flush(ProcessState $state) } /** - * @param ProcessState $state + * {@inheritDoc} * - * @throws ExceptionInterface - * @throws \InvalidArgumentException + * @internal */ public function execute(ProcessState $state) { @@ -99,9 +114,9 @@ public function execute(ProcessState $state) } /** - * @param ProcessState $state + * {@inheritDoc} * - * @return bool + * @internal */ public function next(ProcessState $state) { @@ -114,9 +129,9 @@ public function next(ProcessState $state) } /** - * @param OptionsResolver $resolver + * {@inheritDoc} * - * @throws AccessException + * @internal */ protected function configureOptions(OptionsResolver $resolver) { diff --git a/Task/ObjectUpdaterTask.php b/Task/ObjectUpdaterTask.php index 8cc0ec94..91430c4f 100644 --- a/Task/ObjectUpdaterTask.php +++ b/Task/ObjectUpdaterTask.php @@ -16,8 +16,22 @@ use Symfony\Component\PropertyAccess\PropertyAccessorInterface; /** + * Update an object from input, using a value from input + * * Takes an array containing an object and a value updates an object's property with this value, then return the object + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\ObjectUpdaterTask` + * * **Input**: `array` containing + * - a key `object`: an `array` or an `object` that can be used by the [PropertyAccess component](https://symfony.com/components/PropertyAccess) + * - a key `value` that will be set inside the object + * * **Output**: `array` or `object` from the `object` input array + * + * ##### Options + * + * * `property_path` (`string`, _required_): the property path to use on the object to set the given value * + * @TODO refactor this as a transformer ? * @author Vincent Chalnot */ class ObjectUpdaterTask extends AbstractConfigurableTask diff --git a/Task/PropertyGetterTask.php b/Task/PropertyGetterTask.php index be2dbdb8..ff0dcc08 100644 --- a/Task/PropertyGetterTask.php +++ b/Task/PropertyGetterTask.php @@ -21,6 +21,20 @@ /** * Get a property on the input and return it with PropertyAccessor * + * Accepts an array or an object as an input and read a value from a property path. + * + * See [PropertyAccess Component Reference](https://symfony.com/doc/current/components/property_access.html) for details on property path syntax and behavior. + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\PropertyGetterTask` + * * **Input**: `array` or `object` that can be accessed by the property accessor + * * **Output**: `any`, value of the property extracted from input. + * + * ##### Options + * + * * **`property`** (`string`, _required_): Property path to read from input + * * @author Corentin Bouix */ class PropertyGetterTask extends AbstractConfigurableTask @@ -32,8 +46,7 @@ class PropertyGetterTask extends AbstractConfigurableTask protected $accessor; /** - * @param LoggerInterface $logger - * @param PropertyAccessorInterface $accessor + * @internal */ public function __construct(LoggerInterface $logger, PropertyAccessorInterface $accessor) { @@ -42,9 +55,9 @@ public function __construct(LoggerInterface $logger, PropertyAccessorInterface $ } /** - * @param ProcessState $state + * {@inheritDoc} * - * @throws \Exception + * @internal */ public function execute(ProcessState $state) { @@ -65,10 +78,9 @@ public function execute(ProcessState $state) } /** - * @param OptionsResolver $resolver + * {@inheritDoc} * - * @throws AccessException - * @throws UndefinedOptionsException + * @internal */ protected function configureOptions(OptionsResolver $resolver) { diff --git a/Task/PropertySetterTask.php b/Task/PropertySetterTask.php index 5fee35e5..743ae9e1 100644 --- a/Task/PropertySetterTask.php +++ b/Task/PropertySetterTask.php @@ -19,7 +19,21 @@ use Symfony\Component\PropertyAccess\PropertyAccessorInterface; /** - * Accepts an object or an array as input and sets values from configuration + * Set a property on the input and return it. + * + * See [PropertyAccess Component Reference](https://symfony.com/doc/current/components/property_access.html) for details on property path syntax and behavior. + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\PropertySetterTask` + * * **Input**: `array` or `object` that can be accessed by the property accessor + * * **Output**: Same `array` or `object`, with the property changed + * + * ##### Options + * + * * `values` (`array`, _required_): List of property path => value to set in the input + * + * * * @author Valentin Clavreul * @author Vincent Chalnot @@ -33,8 +47,7 @@ class PropertySetterTask extends AbstractConfigurableTask protected $accessor; /** - * @param LoggerInterface $logger - * @param PropertyAccessorInterface $accessor + * @internal */ public function __construct(LoggerInterface $logger, PropertyAccessorInterface $accessor) { @@ -43,9 +56,9 @@ public function __construct(LoggerInterface $logger, PropertyAccessorInterface $ } /** - * @param ProcessState $state + * {@inheritDoc} * - * @throws \Exception + * @internal */ public function execute(ProcessState $state) { @@ -68,10 +81,9 @@ public function execute(ProcessState $state) } /** - * @param OptionsResolver $resolver + * {@inheritDoc} * - * @throws AccessException - * @throws UndefinedOptionsException + * @internal */ protected function configureOptions(OptionsResolver $resolver) { diff --git a/Task/RowAggregatorTask.php b/Task/RowAggregatorTask.php index 61fafa72..d93a209a 100644 --- a/Task/RowAggregatorTask.php +++ b/Task/RowAggregatorTask.php @@ -21,10 +21,30 @@ use Symfony\Component\OptionsResolver\OptionsResolver; /** - * Wait for defined inputs before passing an aggregated output. - * Should have been a BlockingTask, but due to limitations in the current model, it's a hack using skips and finalize. + * Group inputs using a given property, splitting common values and specific values. * - * @see README.md:Known issues + * For each input this task will get the value under the property defined by the `aggregate_by` option, and try to aggregate similar inputs. + * The idea is to have one level of common values, and one level of specific values. + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\RowAggregatorTask` + * * **Blocking task** + * * **Input**: `array` + * * **Output**: `array` of `array` + * - each 1st level item has for key a value from the property defined by the `aggregate_by` option + * - the 2nd level is an `array` with all the values from the FIRST match that are NOT in `aggregate_columns` + * + an additional property defined by the `aggregation_key` + * - under the 3rd level, defined by `aggregation_key`, there will be a list of item, + * each containing values copied for the columns defined by `aggregate_columns` + * + * ##### Options + * + * * `aggregate_by` (`string`, _required_): the property that will be used for aggregation + * * `aggregation_key` (`string`, _required_): the key in each item of the output that will contain the list of copied input item + * * `aggregate_columns` (`array`, _required_): the list of properties that will be copied for each aggregated item + * + * @example "Resources/examples/task/row_aggregator_task.yaml" */ class RowAggregatorTask extends AbstractConfigurableTask implements BlockingTaskInterface { @@ -37,7 +57,7 @@ class RowAggregatorTask extends AbstractConfigurableTask implements BlockingTask protected $result = []; /** - * @param LoggerInterface $logger + * @internal */ public function __construct(LoggerInterface $logger) { @@ -45,14 +65,8 @@ public function __construct(LoggerInterface $logger) } /** - * Store inputs and once everything has been received, pass to next task - * Once an output has been generated this task is reset, and may wait for another loop - * - * @param ProcessState $state - * - * @throws \UnexpectedValueException - * @throws \InvalidArgumentException - * @throws ExceptionInterface + * {@inheritDoc} + * @internal */ public function execute(ProcessState $state) { @@ -92,7 +106,8 @@ public function execute(ProcessState $state) } /** - * @param ProcessState $state + * {@inheritDoc} + * @internal */ public function proceed(ProcessState $state) { @@ -100,10 +115,8 @@ public function proceed(ProcessState $state) } /** - * @param OptionsResolver $resolver - * - * @throws AccessException - * @throws UndefinedOptionsException + * {@inheritDoc} + * @internal */ protected function configureOptions(OptionsResolver $resolver) { diff --git a/Task/Serialization/DenormalizerTask.php b/Task/Serialization/DenormalizerTask.php index f4b7f6f3..9cc55bfd 100644 --- a/Task/Serialization/DenormalizerTask.php +++ b/Task/Serialization/DenormalizerTask.php @@ -27,6 +27,18 @@ /** * Denormalize input to output with configurable class and format * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\Serialization\DenormalizerTask` + * * **Input**: `array` + * * **Output**: `object`, instance of `class`, as a product of the denormalization + * + * ##### Options + * + * * `class` (`string`, _required_): Destination class for denormalization + * * `format` (`string`, _defaults to_ `null`): Format for denormalization ("json", "xml", ... an empty string should also work) + * * `context` (`array`, _defaults to_ `[]`): Will be passed directly to the 4th parameter of the denormalize method + * * @author Valentin Clavreul * @author Vincent Chalnot */ @@ -36,7 +48,7 @@ class DenormalizerTask extends AbstractConfigurableTask protected $denormalizer; /** - * @param DenormalizerInterface $denormalizer + * @internal */ public function __construct(DenormalizerInterface $denormalizer) { @@ -44,15 +56,9 @@ public function __construct(DenormalizerInterface $denormalizer) } /** - * @param ProcessState $state + * {@inheritDoc} * - * @throws UnexpectedValueException - * @throws RuntimeException - * @throws LogicException - * @throws InvalidArgumentException - * @throws ExtraAttributesException - * @throws BadMethodCallException - * @throws ExceptionInterface + * @internal */ public function execute(ProcessState $state) { @@ -67,10 +73,9 @@ public function execute(ProcessState $state) } /** - * @param OptionsResolver $resolver + * {@inheritDoc} * - * @throws AccessException - * @throws UndefinedOptionsException + * @internal */ protected function configureOptions(OptionsResolver $resolver) { diff --git a/Task/Serialization/NormalizerTask.php b/Task/Serialization/NormalizerTask.php index 9323ce91..fae0301c 100644 --- a/Task/Serialization/NormalizerTask.php +++ b/Task/Serialization/NormalizerTask.php @@ -23,6 +23,17 @@ /** * Normalize input to output with configurable format + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\Serialization\NormalizerTask` + * * **Input**: `object`, any normalizable object + * * **Output**: `array`, a normalized value as an array + * + * ##### Options + * + * * `format` (`string`, _required_): Format for normalization ("json", "xml", ... an empty string should also work) + * * `context` (`array`, _defaults to_ `[]`): Will be passed directly to the third parameter of the normalize method * * @author Valentin Clavreul * @author Vincent Chalnot @@ -33,7 +44,7 @@ class NormalizerTask extends AbstractConfigurableTask protected $normalizer; /** - * @param NormalizerInterface $normalizer + * @internal */ public function __construct(NormalizerInterface $normalizer) { @@ -41,12 +52,9 @@ public function __construct(NormalizerInterface $normalizer) } /** - * @param ProcessState $state + * {@inheritDoc} * - * @throws LogicException - * @throws InvalidArgumentException - * @throws CircularReferenceException - * @throws ExceptionInterface + * @internal */ public function execute(ProcessState $state) { @@ -65,10 +73,9 @@ public function execute(ProcessState $state) } /** - * @param OptionsResolver $resolver + * {@inheritDoc} * - * @throws AccessException - * @throws UndefinedOptionsException + * @internal */ protected function configureOptions(OptionsResolver $resolver) { diff --git a/Task/SimpleBatchTask.php b/Task/SimpleBatchTask.php index 4ba46193..076377b9 100644 --- a/Task/SimpleBatchTask.php +++ b/Task/SimpleBatchTask.php @@ -18,7 +18,21 @@ use Symfony\Component\OptionsResolver\OptionsResolver; /** - * Simple example of how to manage an internal buffer for batch processing + * Group elements by batch of a defined size. + * + * Simple example of how to manage an internal buffer for batch processing. + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\SimpleBatchTask` + * * **Flushable task** + * * **Input**: `any` + * * **Output**: `array`, containing received inputs since previous flush + * + * ##### Options + * + * * `batch_count` (`int` _defaults to_ `10`): description + * * * @author Vincent Chalnot */ @@ -28,7 +42,8 @@ class SimpleBatchTask extends AbstractConfigurableTask implements FlushableTaskI protected $elements = []; /** - * @param ProcessState $state + * {@inheritDoc} + * @internal */ public function flush(ProcessState $state) { @@ -41,10 +56,8 @@ public function flush(ProcessState $state) } /** - * @param ProcessState $state - * - * @throws ExceptionInterface - * @throws \InvalidArgumentException + * {@inheritDoc} + * @internal */ public function execute(ProcessState $state) { @@ -60,9 +73,8 @@ public function execute(ProcessState $state) } /** - * @param OptionsResolver $resolver - * - * @throws AccessException + * {@inheritDoc} + * @internal */ protected function configureOptions(OptionsResolver $resolver) { diff --git a/Task/SkipEmptyTask.php b/Task/SkipEmptyTask.php index af357094..b848fe8a 100644 --- a/Task/SkipEmptyTask.php +++ b/Task/SkipEmptyTask.php @@ -14,13 +14,19 @@ use CleverAge\ProcessBundle\Model\TaskInterface; /** - * Allow to skip the execution on empty input. - * Useful when combined with an aggregator task + * Skip empty inputs. + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\SkipEmptyTask` + * * **Input**: `any` + * * **Output**: `any`, same as the input, if not empty */ class SkipEmptyTask implements TaskInterface { /** - * @param ProcessState $state + * {@inheritDoc} + * @internal */ public function execute(ProcessState $state) { diff --git a/Task/SplitJoinLineTask.php b/Task/SplitJoinLineTask.php index e9a19671..51d2e160 100644 --- a/Task/SplitJoinLineTask.php +++ b/Task/SplitJoinLineTask.php @@ -14,14 +14,33 @@ use Symfony\Component\OptionsResolver\OptionsResolver; /** - * Split a single line into multiple lines based on multiple columns and split characters + * Split a single line into multiple lines based on multiple columns and split characters. + * + * For each input, it will take each value from columns referenced by `split_columns`, split it with `split_character`, + * and for each part, produce an output item that will contain all data from input + a column with the key from `join_column` containing the current part. + * + * This might produce more output than input, with semi-duplicated lines. + * + * ##### Task or Transformer reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\SplitJoinLineTask` + * * **Iterable task** + * * **Input**: `array`, description + * * **Output**: `type`, description + * + * ##### Options + * + * * `split_columns` (`array`, _required_): the list of properties to split + * * `join_column` (`string`, _required_): the name of the property that will be included in the output, containing a part of a split value + * * `split_character` (`string`, _defaults to_ `,`): the delimiter for split values * * @author Vincent Chalnot */ class SplitJoinLineTask extends AbstractIterableOutputTask { /** - * {@inheritdoc} + * {@inheritDoc} + * @internal */ public function next(ProcessState $state): bool { @@ -34,7 +53,8 @@ public function next(ProcessState $state): bool } /** - * @param OptionsResolver $resolver + * {@inheritDoc} + * @internal */ protected function configureOptions(OptionsResolver $resolver): void { @@ -54,9 +74,8 @@ protected function configureOptions(OptionsResolver $resolver): void } /** - * @param ProcessState $state - * - * @return \Iterator + * {@inheritDoc} + * @internal */ protected function initializeIterator(ProcessState $state): \Iterator { diff --git a/Task/StopTask.php b/Task/StopTask.php index 9b75034c..eb2ee401 100644 --- a/Task/StopTask.php +++ b/Task/StopTask.php @@ -15,11 +15,18 @@ /** * Allows to directly stop a process, marking it as failed + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\StopTask` + * * **Input**: _ignored_ + * * **Output**: _none_ */ class StopTask implements TaskInterface { /** * {@inheritdoc} + * @internal */ public function execute(ProcessState $state) { diff --git a/Task/TransformerTask.php b/Task/TransformerTask.php index 8f44fef2..761679a0 100644 --- a/Task/TransformerTask.php +++ b/Task/TransformerTask.php @@ -28,7 +28,19 @@ use Symfony\Component\OptionsResolver\OptionsResolver; /** - * Transform an array of data based on mapping and sub-transformers + * Transform an array of data using transformers + * + * See transformers references. + * + * ##### Task reference + * + * * **Service**: `CleverAge\ProcessBundle\Task\TransformerTask` + * * **Input**: `any`, it should match the 1st expected input of the transform chain + * * **Output**: `any`, result of the transform chain + * + * ##### Options + * + * * `transformers` (`array`, _required_): List of transformers, see {@see TransformerTrait} * * @author Valentin Clavreul * @author Vincent Chalnot @@ -44,9 +56,7 @@ class TransformerTask extends AbstractConfigurableTask protected $transformer; /** - * @param LoggerInterface $logger - * @param TransformerRegistry $transformerRegistry - * + * @internal */ public function __construct(LoggerInterface $logger, TransformerRegistry $transformerRegistry) { @@ -55,17 +65,9 @@ public function __construct(LoggerInterface $logger, TransformerRegistry $transf } /** - * @param ProcessState $state + * {@inheritDoc} * - * @throws ExceptionInterface - * @throws MissingTransformerException - * @throws \UnexpectedValueException - * @throws AccessException - * @throws InvalidOptionsException - * @throws MissingOptionsException - * @throws NoSuchOptionException - * @throws OptionDefinitionException - * @throws UndefinedOptionsException + * @internal */ public function execute(ProcessState $state) { @@ -84,16 +86,9 @@ public function execute(ProcessState $state) } /** - * @param OptionsResolver $resolver + * {@inheritDoc} * - * @throws UndefinedOptionsException - * @throws OptionDefinitionException - * @throws NoSuchOptionException - * @throws MissingOptionsException - * @throws InvalidOptionsException - * @throws AccessException - * @throws MissingTransformerException - * @throws ExceptionInterface + * @internal */ protected function configureOptions(OptionsResolver $resolver) { diff --git a/Transformer/TransformerTrait.php b/Transformer/TransformerTrait.php index 30133616..20d19c64 100644 --- a/Transformer/TransformerTrait.php +++ b/Transformer/TransformerTrait.php @@ -99,6 +99,8 @@ protected function configureTransformersOptions(OptionsResolver $resolver, $opti /** * Transform the list of transformer codes + options into a list of Closure (better performances) * + * @internal + * * @param Options $options * @param $transformers * diff --git a/Validator/ConstraintLoader.php b/Validator/ConstraintLoader.php index a7c623cd..cc6c64b9 100644 --- a/Validator/ConstraintLoader.php +++ b/Validator/ConstraintLoader.php @@ -13,6 +13,9 @@ use Symfony\Component\Validator\Mapping\ClassMetadata; use Symfony\Component\Validator\Mapping\Loader\AbstractLoader; +/** + * @internal + */ class ConstraintLoader extends AbstractLoader { public function loadClassMetadata(ClassMetadata $metadata) diff --git a/phpdoc.xml b/phpdoc.xml new file mode 100644 index 00000000..18d30437 --- /dev/null +++ b/phpdoc.xml @@ -0,0 +1,36 @@ + + + + Clever Age - Process Bundle + + var/doc + + + + + . + + + + Configuration/**/* + Context/**/* + DependencyInjection/**/* + EventDispatcher/**/* + ExpressionLanguage/**/* + Logger/**/* + Validator/**/* + + + .github/**/* + .phpdoc/**/* + hooks/**/* + Resources/**/* + Tests/**/* + var/**/* + vendor/**/* + CleverAgeProcessBundle.php + + public + + +