mediashare/simple-javascript-compilation

[UnArchived] Compiles JavaScript code through a series of actions.

dev-master 2020-12-19 19:13 UTC

Requires

• php: ^7.0
• ext-bcmath: *
• ext-curl: *
• ext-mbstring: *
• krowinski/bcmath-extended: ^4.2.1
• matthiasmullie/minify: ^1.3
• myclabs/php-enum: ^1.6.6

Requires (Dev)

• phpunit/phpunit: ^6.5.5

MIT

• Kyran Rana

README

This library supports compiling simple JavaScript declarations and expressions without the need for PHP V8JS.

Supported in expressions:

- Global methods

    - String.fromCharCode
    - atob
    - eval
    - escape

- Primitive types

    - Boolean  
    - Integer
    
        - toFixed
    
    - String
    
       - charCodeAt
       - italics
       - length
    
    - Null
    - Undefined 

- Arrays

Architecture

This library consists of 4 main classes.

ExpressionStreamReader

• Reads through and emits events when entering / passing key areas of an expression.

• Events emitted:

  • EXPRESSION_START

    {
        castAndNegations:   Array<String>           // casts and negations (! +) before expression
    }
  

  • EXPRESSION_END

    {
        additionalOps:      Array<AdditionalCall>   // function and index calls on result of expression
        operator:           Operator                // operator
    }
  

  • ARRAY_START

    {
        castAndNegations:   Array<String>           // casts and negations (! +) before array
    }
  

  • ARRAY_END

    {
        additionalOps:      Array<AdditionalCall>   // function and index calls on result of array
        operator:           Operator                // operator
    }
  

  • BOOLEAN

    {
        value:              String                  // true / false
        additionalOps:      Array<AdditionalCall>   // function or index calls on boolean
        castsAndNegations:  Array<String>           // casts and negations (! +) before boolean
        operator:           Operator                // operator
    }
  

  • INTEGER

    {
        value:              String                  // integer / NaN / Infinity / -Infinity
        additionalOps:      Array<AdditionalCall>   // function or index calls on integer
        castsAndNegations:  Array<String>           // casts and negations (! +) before integer
        operator:           Operator                // operator
    }
  

  • STRING

    {
        value:              String                  // string
        additionalOps:      Array<AdditionalCall>   // function or index calls on string
        castsAndNegations:  Array<String>           // casts and negations (! +) before string
        operator:           Operator                // operator
    }
  

  • NULL

    {
        value:              String                  // null
        additionalOps:      Array<AdditionalCall>   // functions or index calls on null
        castsAndNegations:  Array<String>           // casts and negations (! +) before null
        operator:           Operator                // operator
    }
  

  • UNDEFINED

    {
        value:              String                  // undefined
        additionalOps:      Array<AdditionalCall>   // functions or index calls on undefined
        castsAndNegations:  Array<String>           // casts and negations (! +) before undefined
        operator:           Operator                // operator
    }
  

  • DEFINITION

    {
        name:               String                  // definition name
        additionalOps:      Array<AdditionalCall>   // function or index calls on definition value
        castsAndNegations:  Array<String>           // casts and negations (! +) before definition
        operator:           Operator                // operator
    }
  

  • FUNCTION_START

    {
        castsAndNegations:  Array<String>           // casts and negations (! +) before function call
    }
  

  • FUNCTION_NAME

    {
        name:               String                  // function name
    }
  

  • FUNCTION_ARG

    {
        argData:            Array<Event>            // collection of expression events 
    }
  

  • FUNCTION_END

    {
        additionalOps:      Array<AdditionalCall>   // function or index calls on function
        operator:           Array<String>           // operator
    }
  

  • INLINE_FUNCTION_START

    {
        castsAndNegations:  Array<String>           // casts and negations (! +) before inline function
    }
  

  • INLINE_FUNCTION_ARG

    {
        arg:                Array<Event>            // collection of expression events
    }
  

  • INLINE_FUNCTION_CODE

    {
        value:              String                  // inline function code
    }
  

  • INLINE_FUNCTION_ARG_DATA

    {
        argData:             Array<Event>            // collection of expression events
    }
  

  • INLINE_FUNCTION_END

    {
        additionalOps:      Array<AdditionalCall>   // function or index calls on inline function
        operator:           Operator                // operator
    }
  

  • FUNCTION_ONLY

    {
        castsAndNegations:  Array<String>           // casts and negations (! +) before function name
        name:               String                  // function name
        operator:           Operator                // operator
    }
  

• Models used:

  • AdditionalCall

    {
        type:               String                  // property or function
        name:               Array<Events>           // property or function name
        args:               Array<Array<Event>>     // function arguments
    }
  

DeclarationStreamReader

• Reads through and emits event for each declaration in code consisting of only declarations.

• Event emitted:

  • DECLARATION

    {
        declaration:        String                  // declaration name
        operator:           Operator                // operator
        value:              String                  // expression
    }
  

ExpressionInterpreter

• Interprets expression using ExpressionStreamReader and in cases where inline functions are used DeclarationInterpreter, ultimately returning a CustomDataType.

<?php
use SimpleJavaScriptCompilation\ExpressionInterpreterImpl;
use SimpleJavaScriptCompilation\Model\Context;

$customDataType = ExpressionInterpreterImpl::instance()->interpretExpression('2+2+"hey there"', new Context());
?>

• A Context is maintained throughout interpreting the expression which holds arbitary data which is required for processing certain areas of the expression. If you want to pass your own definitions to the expression interpreter, you can do the following:

<?php
use SimpleJavaScriptCompilation\ExpressionInterpreterImpl;
use SimpleJavaScriptCompilation\Model\Context;
use SimpleJavaScriptCompilation\Model\DataType\CustomString;
use SimpleJavaScriptCompilation\Model\DataType\CustomInteger;
use SimpleJavaScriptCompilation\Model\DataType;

$ctx = new Context();
$ctx->setCtxVar("a", new CustomInteger(new DataType(["value" => "2"])));
$ctx->setCtxVar("c", new CustomString(new DataType(["value" => '"hello, "'])));

// You can also set functions in the context too
// See a list of supported functions in SimpleJavaScriptCompilation\Model\FunctionMap\GlobalFunctionMap
$ctx->setCtxFunc("e", "SimpleJavaScriptCompilation\Model\FunctionMap\GlobalFunctionMap::atob");

$customDataType = ExpressionInterpreterImpl::instance()->interpretExpression('a+2+c+"hey there"+(function(){ return "sup"; })()', $ctx);
?>

• More examples of usage can be found in /src/test/ExpressionInterpreterImplTest.php

• Models covered:

  • Context

    {
        ctxStack:       Array<Mixed>                        // INTERNAL ONLY
        ctxTmp:         Array<String, Mixed>                // INTERNAL ONLY
        ctxVarMap:      Array<String, CustomDataType>       // variables 
        ctxFuncMap:     Array<String, Mixed>                // functions
        ctxSum:         CustomDataType                      // computed result to start calculation with
    }
  

  • CustomDataType

    {
        dataType:       DataType                            // underlying data type model
          
        merge(DataType $dataType): CustomDataType
        add(DataType $dataType): CustomDataType             // adds data type models and determines new CustomDataType
        subtract(DataType $dataType): CustomDataType        // subtracts data type models and determines new CustomDataType
        multiply(DataType $dataType): CustomDataType        // multiplies data type models and determines new CustomDataType
        divide(DataType $dataType): CustomDataType          // divides data type models and determines new CustomDataType
    }
  

  • CustomDataType implementations

    • CustomInteger - handles calculation for JavaScript integers (numbers / NaN / Infinity)
    • CustomString - handles calculation for JavaScript strings
    • CustomBoolean - handles calculation for JavaScript booleans (true / false)
    • CustomNull - handles calculation for JavaScript null
    • CustomUndefined - handles calculation for JavaScript undefined

  • DataType

    {
        dataType:               DataTypeEnum                // type of data
        castsAndNegations:      Array<String>               // casts and negations (! +) before data type
        value:                  String                      // data type value
        additionalCalls:        Array<AdditionalCall>       // function or index calls on data type value
        operator:               Operator                    // operator
    }
  

DeclarationInterpreter

• Interprets a group of declarations using DeclarationStreamReader and ExpressionInterpreter, ultimately returning a Context.

<?php
use SimpleJavaScriptCompilation\DeclarationInterpreterImpl;
use SimpleJavaScriptCompilation\Model\Context;

$ctx = DeclarationInterpreterImpl::instance()->interpretDeclarations('var a = 2+2; var b = "hey there";', new Context());
?>

<?php
use SimpleJavaScriptCompilation\DeclarationInterpreterImpl;
use SimpleJavaScriptCompilation\Model\DataType\CustomInteger;
use SimpleJavaScriptCompilation\Model\Context;
use SimpleJavaScriptCompilation\Model\DataType;

// You can also pass your own variables and functions to the context
// Refer to examples in ExpressionInterpreter section
$ctx = new Context();
$ctx->setCtxVar("a", new CustomInteger(new DataType(['value' => '4'])));

$ctx = DeclarationInterpreterImpl::instance()->interpretDeclarations('var a = 2+2; var b = "hey there";', $ctx);
?>

• More examples of usage can be found in /src/test/DeclarationInterpreterImplTest.php