otrs -> rel-6_0 API documentation

NAME

Kernel::System::Main - main object

DESCRIPTION

All main functions to load modules, die, and handle files.

PUBLIC INTERFACE

new()

create new object. Do not use it directly, instead use:

my $MainObject = $Kernel::OM->Get('Kernel::System::Main');

Require()

require/load a module

my $Loaded = $MainObject->Require(
    'Kernel::System::Example',
    Silent => 1,                # optional, no log entry if module was not found
);

RequireBaseClass()

require/load a module and add it as a base class to the calling package, if not already present (this check is needed for persistent environments).

my $Loaded = $MainObject->RequireBaseClass(
    'Kernel::System::Example',
);

Die()

to die

$MainObject->Die('some message to die');

FilenameCleanUp()

to clean up filenames which can be used in any case (also quoting is done)

my $Filename = $MainObject->FilenameCleanUp(
    Filename => 'me_to/alal.xml',
    Type     => 'Local', # Local|Attachment|MD5
);

my $Filename = $MainObject->FilenameCleanUp(
    Filename => 'some:file.xml',
    Type     => 'MD5', # Local|Attachment|MD5
);

FileRead()

to read files from file system

my $ContentSCALARRef = $MainObject->FileRead(
    Directory => 'c:\some\location',
    Filename  => 'file2read.txt',
    # or Location
    Location  => 'c:\some\location\file2read.txt',
);

my $ContentARRAYRef = $MainObject->FileRead(
    Directory => 'c:\some\location',
    Filename  => 'file2read.txt',
    # or Location
    Location  => 'c:\some\location\file2read.txt',

    Result    => 'ARRAY', # optional - SCALAR|ARRAY
);

my $ContentSCALARRef = $MainObject->FileRead(
    Directory       => 'c:\some\location',
    Filename        => 'file2read.txt',
    # or Location
    Location        => 'c:\some\location\file2read.txt',

    Mode            => 'binmode', # optional - binmode|utf8
    Type            => 'Local',   # optional - Local|Attachment|MD5
    Result          => 'SCALAR',  # optional - SCALAR|ARRAY
    DisableWarnings => 1,         # optional
);

FileWrite()

to write data to file system

my $FileLocation = $MainObject->FileWrite(
    Directory => 'c:\some\location',
    Filename  => 'file2write.txt',
    # or Location
    Location  => 'c:\some\location\file2write.txt',

    Content   => \$Content,
);

my $FileLocation = $MainObject->FileWrite(
    Directory  => 'c:\some\location',
    Filename   => 'file2write.txt',
    # or Location
    Location   => 'c:\some\location\file2write.txt',

    Content    => \$Content,
    Mode       => 'binmode', # binmode|utf8
    Type       => 'Local',   # optional - Local|Attachment|MD5
    Permission => '644',     # optional - unix file permissions
);

Platform note: MacOS (HFS+) stores filenames as Unicode NFD internally, and DirectoryRead() will also report them as NFD.

FileDelete()

to delete a file from file system

my $Success = $MainObject->FileDelete(
    Directory       => 'c:\some\location',
    Filename        => 'me_to/alal.xml',
    # or Location
    Location        => 'c:\some\location\me_to\alal.xml'

    Type            => 'Local',   # optional - Local|Attachment|MD5
    DisableWarnings => 1, # optional
);

FileGetMTime()

get timestamp of file change time

my $FileMTime = $MainObject->FileGetMTime(
    Directory => 'c:\some\location',
    Filename  => 'me_to/alal.xml',
    # or Location
    Location  => 'c:\some\location\me_to\alal.xml'
);

MD5sum()

get an MD5 sum of a file or a string

my $MD5Sum = $MainObject->MD5sum(
    Filename => '/path/to/me_to_alal.xml',
);

my $MD5Sum = $MainObject->MD5sum(
    String => \$SomeString,
);

# note: needs more memory!
my $MD5Sum = $MainObject->MD5sum(
    String => $SomeString,
);

Dump()

dump variable to an string

my $Dump = $MainObject->Dump(
    $SomeVariable,
);

my $Dump = $MainObject->Dump(
    {
        Key1 => $SomeVariable,
    },
);

dump only in ascii characters (> 128 will be marked as \x{..})

my $Dump = $MainObject->Dump(
    $SomeVariable,
    'ascii', # ascii|binary - default is binary
);

DirectoryRead()

reads a directory and returns an array with results.

my @FilesInDirectory = $MainObject->DirectoryRead(
    Directory => '/tmp',
    Filter    => 'Filenam*',
);

my @FilesInDirectory = $MainObject->DirectoryRead(
    Directory => $Path,
    Filter    => '*',
);

read all files in subdirectories as well (recursive):

my @FilesInDirectory = $MainObject->DirectoryRead(
    Directory => $Path,
    Filter    => '*',
    Recursive => 1,
);

You can pass several additional filters at once:

my @FilesInDirectory = $MainObject->DirectoryRead(
    Directory => '/tmp',
    Filter    => \@MyFilters,
);

The result strings are absolute paths, and they are converted to utf8.

Use the 'Silent' parameter to suppress log messages when a directory does not have to exist:

my @FilesInDirectory = $MainObject->DirectoryRead(
    Directory => '/special/optional/directory/',
    Filter    => '*',
    Silent    => 1,     # will not log errors if the directory does not exist
);

Platform note: MacOS (HFS+) stores filenames as Unicode NFD internally, and DirectoryRead() will also report them as NFD.

GenerateRandomString()

generate a random string of defined length, and of a defined alphabet. defaults to a length of 16 and alphanumerics ( 0..9, A-Z and a-z).

my $String = $MainObject->GenerateRandomString();

returns

$String = 'mHLOx7psWjMe5Pj7';

with specific length:

my $String = $MainObject->GenerateRandomString(
    Length => 32,
);

returns

$String = 'azzHab72wIlAXDrxHexsI5aENsESxAO7';

with specific length and alphabet:

my $String = $MainObject->GenerateRandomString(
    Length     => 32,
    Dictionary => [ 0..9, 'a'..'f' ], # hexadecimal
    );

returns

$String = '9fec63d37078fe72f5798d2084fea8ad';

TERMS AND CONDITIONS

This software is part of the OTRS project (https://otrs.org/).

This software comes with ABSOLUTELY NO WARRANTY. For details, see the enclosed file COPYING for license information (GPL). If you did not receive this file, see https://www.gnu.org/licenses/gpl-3.0.txt.